feat: add prompts to conversational history when using structured output

- Modified structured_output_async to add prompts to conversation history
- Modified structured_output_async to add structured output results to conversation history
- Updated docstrings to reflect new behavior
- Updated all related tests to verify conversation history is updated
- Updated hook tests to expect MessageAddedEvent for prompts and outputs
- Maintains backward compatibility

Resolves strands-agents#810

Author: aditya270520

src/strands/agent/agent.py

@@ -441,7 +441,7 @@ async def invoke_async(self, prompt: AgentInput = None, **kwargs: Any) -> AgentR
     def structured_output(self, output_model: Type[T], prompt: AgentInput = None) -> T:
         """This method allows you to get structured output from the agent.
 
-        If you pass in a prompt, it will be used temporarily without adding it to the conversation history.
+        If you pass in a prompt, it will be added to the conversation history along with the structured output result.
         If you don't pass in a prompt, it will use only the existing conversation history to respond.
 
         For smaller models, you may want to use the optional prompt to add additional instructions to explicitly
@@ -470,7 +470,7 @@ def execute() -> T:
     async def structured_output_async(self, output_model: Type[T], prompt: AgentInput = None) -> T:
         """This method allows you to get structured output from the agent.
 
-        If you pass in a prompt, it will be used temporarily without adding it to the conversation history.
+        If you pass in a prompt, it will be added to the conversation history along with the structured output result.
         If you don't pass in a prompt, it will use only the existing conversation history to respond.
 
         For smaller models, you may want to use the optional prompt to add additional instructions to explicitly
@@ -479,7 +479,7 @@ async def structured_output_async(self, output_model: Type[T], prompt: AgentInpu
         Args:
             output_model: The output model (a JSON schema written as a Pydantic BaseModel)
                 that the agent will use when responding.
-            prompt: The prompt to use for the agent (will not be added to conversation history).
+            prompt: The prompt to use for the agent (will be added to conversation history).
 
         Raises:
             ValueError: If no conversation history or prompt is provided.
@@ -492,7 +492,13 @@ async def structured_output_async(self, output_model: Type[T], prompt: AgentInpu
                 if not self.messages and not prompt:
                     raise ValueError("No conversation history or prompt provided")
 
-                temp_messages: Messages = self.messages + self._convert_prompt_to_messages(prompt)
+                # Add prompt to conversation history if provided
+                if prompt:
+                    prompt_messages = self._convert_prompt_to_messages(prompt)
+                    for message in prompt_messages:
+                        self._append_message(message)
+
+                temp_messages: Messages = self.messages
 
                 structured_output_span.set_attributes(
                     {
@@ -519,7 +525,16 @@ async def structured_output_async(self, output_model: Type[T], prompt: AgentInpu
                 structured_output_span.add_event(
                     "gen_ai.choice", attributes={"message": serialize(event["output"].model_dump())}
                 )
-                return event["output"]
+                
+                # Add structured output result to conversation history
+                result = event["output"]
+                assistant_message = {
+                    "role": "assistant",
+                    "content": [{"text": f"Structured output ({output_model.__name__}): {result.model_dump_json()}"}]
+                }
+                self._append_message(assistant_message)
+                
+                return result
 
             finally:
                 self.hooks.invoke_callbacks(AfterInvocationEvent(agent=self))

tests/strands/agent/test_agent.py

@@ -985,6 +985,9 @@ def test_agent_structured_output(agent, system_prompt, user, agenerator):
     agent.tracer = mock_strands_tracer
 
     agent.model.structured_output = unittest.mock.Mock(return_value=agenerator([{"output": user}]))
+    agent.hooks = unittest.mock.MagicMock()
+    agent.hooks.invoke_callbacks = unittest.mock.Mock()
+    agent.callback_handler = unittest.mock.Mock()
 
     prompt = "Jane Doe is 30 years old and her email is jane@doe.com"
 
@@ -995,12 +998,31 @@ def test_agent_structured_output(agent, system_prompt, user, agenerator):
     exp_result = user
     assert tru_result == exp_result
 
-    # Verify conversation history is not polluted
-    assert len(agent.messages) == initial_message_count
+    # Verify conversation history is updated with prompt and structured output
+    assert len(agent.messages) == initial_message_count + 2
+    
+    # Verify the prompt was added to conversation history
+    user_message_added = any(
+        msg['role'] == 'user' and prompt in msg['content'][0]['text']
+        for msg in agent.messages
+    )
+    assert user_message_added, "User prompt should be added to conversation history"
+    
+    # Verify the structured output was added to conversation history
+    assistant_message_added = any(
+        msg['role'] == 'assistant' and 'Structured output (User):' in msg['content'][0]['text']
+        for msg in agent.messages
+    )
+    assert assistant_message_added, "Structured output should be added to conversation history"
 
-    # Verify the model was called with temporary messages array
+    # Verify the model was called with all messages (including the added prompt)
     agent.model.structured_output.assert_called_once_with(
-        type(user), [{"role": "user", "content": [{"text": prompt}]}], system_prompt=system_prompt
+        type(user), 
+        [
+            {"role": "user", "content": [{"text": prompt}]},
+            {"role": "assistant", "content": [{"text": f"Structured output (User): {user.model_dump_json()}"}]}
+        ], 
+        system_prompt=system_prompt
     )
 
     mock_span.set_attributes.assert_called_once_with(
@@ -1052,12 +1074,31 @@ def test_agent_structured_output_multi_modal_input(agent, system_prompt, user, a
     exp_result = user
     assert tru_result == exp_result
 
-    # Verify conversation history is not polluted
-    assert len(agent.messages) == initial_message_count
+    # Verify conversation history is updated with prompt and structured output
+    assert len(agent.messages) == initial_message_count + 2
+    
+    # Verify the multi-modal prompt was added to conversation history
+    user_message_added = any(
+        msg['role'] == 'user' and 'Please describe the user in this image' in msg['content'][0]['text']
+        for msg in agent.messages
+    )
+    assert user_message_added, "Multi-modal user prompt should be added to conversation history"
+    
+    # Verify the structured output was added to conversation history
+    assistant_message_added = any(
+        msg['role'] == 'assistant' and 'Structured output (User):' in msg['content'][0]['text']
+        for msg in agent.messages
+    )
+    assert assistant_message_added, "Structured output should be added to conversation history"
 
-    # Verify the model was called with temporary messages array
+    # Verify the model was called with all messages (including the added prompt)
     agent.model.structured_output.assert_called_once_with(
-        type(user), [{"role": "user", "content": prompt}], system_prompt=system_prompt
+        type(user), 
+        [
+            {"role": "user", "content": prompt},
+            {"role": "assistant", "content": [{"text": f"Structured output (User): {user.model_dump_json()}"}]}
+        ], 
+        system_prompt=system_prompt
     )
 
     mock_span.add_event.assert_called_with(
@@ -1069,6 +1110,9 @@ def test_agent_structured_output_multi_modal_input(agent, system_prompt, user, a
 @pytest.mark.asyncio
 async def test_agent_structured_output_in_async_context(agent, user, agenerator):
     agent.model.structured_output = unittest.mock.Mock(return_value=agenerator([{"output": user}]))
+    agent.hooks = unittest.mock.MagicMock()
+    agent.hooks.invoke_callbacks = unittest.mock.Mock()
+    agent.callback_handler = unittest.mock.Mock()
 
     prompt = "Jane Doe is 30 years old and her email is jane@doe.com"
 
@@ -1079,13 +1123,30 @@ async def test_agent_structured_output_in_async_context(agent, user, agenerator)
     exp_result = user
     assert tru_result == exp_result
 
-    # Verify conversation history is not polluted
-    assert len(agent.messages) == initial_message_count
+    # Verify conversation history is updated with prompt and structured output
+    assert len(agent.messages) == initial_message_count + 2
+    
+    # Verify the prompt was added to conversation history
+    user_message_added = any(
+        msg['role'] == 'user' and prompt in msg['content'][0]['text']
+        for msg in agent.messages
+    )
+    assert user_message_added, "User prompt should be added to conversation history"
+    
+    # Verify the structured output was added to conversation history
+    assistant_message_added = any(
+        msg['role'] == 'assistant' and 'Structured output (User):' in msg['content'][0]['text']
+        for msg in agent.messages
+    )
+    assert assistant_message_added, "Structured output should be added to conversation history"
 
 
 def test_agent_structured_output_without_prompt(agent, system_prompt, user, agenerator):
     """Test that structured_output works with existing conversation history and no new prompt."""
     agent.model.structured_output = unittest.mock.Mock(return_value=agenerator([{"output": user}]))
+    agent.hooks = unittest.mock.MagicMock()
+    agent.hooks.invoke_callbacks = unittest.mock.Mock()
+    agent.callback_handler = unittest.mock.Mock()
 
     # Add some existing messages to the agent
     existing_messages = [
@@ -1100,17 +1161,27 @@ def test_agent_structured_output_without_prompt(agent, system_prompt, user, agen
     exp_result = user
     assert tru_result == exp_result
 
-    # Verify conversation history is unchanged
-    assert len(agent.messages) == initial_message_count
-    assert agent.messages == existing_messages
+    # Verify conversation history is updated with structured output only (no prompt added)
+    assert len(agent.messages) == initial_message_count + 1
+    
+    # Verify the structured output was added to conversation history
+    assistant_message_added = any(
+        msg['role'] == 'assistant' and 'Structured output (User):' in msg['content'][0]['text']
+        for msg in agent.messages
+    )
+    assert assistant_message_added, "Structured output should be added to conversation history"
 
-    # Verify the model was called with existing messages only
-    agent.model.structured_output.assert_called_once_with(type(user), existing_messages, system_prompt=system_prompt)
+    # Verify the model was called with existing messages plus the added structured output
+    expected_messages = existing_messages + [{"role": "assistant", "content": [{"text": f"Structured output (User): {user.model_dump_json()}"}]}]
+    agent.model.structured_output.assert_called_once_with(type(user), expected_messages, system_prompt=system_prompt)
 
 
 @pytest.mark.asyncio
 async def test_agent_structured_output_async(agent, system_prompt, user, agenerator):
     agent.model.structured_output = unittest.mock.Mock(return_value=agenerator([{"output": user}]))
+    agent.hooks = unittest.mock.MagicMock()
+    agent.hooks.invoke_callbacks = unittest.mock.Mock()
+    agent.callback_handler = unittest.mock.Mock()
 
     prompt = "Jane Doe is 30 years old and her email is jane@doe.com"
 
@@ -1121,12 +1192,31 @@ async def test_agent_structured_output_async(agent, system_prompt, user, agenera
     exp_result = user
     assert tru_result == exp_result
 
-    # Verify conversation history is not polluted
-    assert len(agent.messages) == initial_message_count
+    # Verify conversation history is updated with prompt and structured output
+    assert len(agent.messages) == initial_message_count + 2
+    
+    # Verify the prompt was added to conversation history
+    user_message_added = any(
+        msg['role'] == 'user' and prompt in msg['content'][0]['text']
+        for msg in agent.messages
+    )
+    assert user_message_added, "User prompt should be added to conversation history"
+    
+    # Verify the structured output was added to conversation history
+    assistant_message_added = any(
+        msg['role'] == 'assistant' and 'Structured output (User):' in msg['content'][0]['text']
+        for msg in agent.messages
+    )
+    assert assistant_message_added, "Structured output should be added to conversation history"
 
-    # Verify the model was called with temporary messages array
+    # Verify the model was called with all messages (including the added prompt)
     agent.model.structured_output.assert_called_once_with(
-        type(user), [{"role": "user", "content": [{"text": prompt}]}], system_prompt=system_prompt
+        type(user), 
+        [
+            {"role": "user", "content": [{"text": prompt}]},
+            {"role": "assistant", "content": [{"text": f"Structured output (User): {user.model_dump_json()}"}]}
+        ], 
+        system_prompt=system_prompt
     )
 
 

tests/strands/agent/test_agent_hooks.py

@@ -267,12 +267,14 @@ def test_agent_structured_output_hooks(agent, hook_provider, user, agenerator):
 
     length, events = hook_provider.get_events()
 
-    assert length == 2
+    assert length == 4  # BeforeInvocationEvent, MessageAddedEvent (prompt), MessageAddedEvent (output), AfterInvocationEvent
 
     assert next(events) == BeforeInvocationEvent(agent=agent)
+    assert next(events) == MessageAddedEvent(agent=agent, message=agent.messages[0])  # Prompt added
+    assert next(events) == MessageAddedEvent(agent=agent, message=agent.messages[1])  # Output added
     assert next(events) == AfterInvocationEvent(agent=agent)
 
-    assert len(agent.messages) == 0  # no new messages added
+    assert len(agent.messages) == 2  # prompt and structured output added
 
 
 @pytest.mark.asyncio
@@ -284,9 +286,11 @@ async def test_agent_structured_async_output_hooks(agent, hook_provider, user, a
 
     length, events = hook_provider.get_events()
 
-    assert length == 2
+    assert length == 4  # BeforeInvocationEvent, MessageAddedEvent (prompt), MessageAddedEvent (output), AfterInvocationEvent
 
     assert next(events) == BeforeInvocationEvent(agent=agent)
+    assert next(events) == MessageAddedEvent(agent=agent, message=agent.messages[0])  # Prompt added
+    assert next(events) == MessageAddedEvent(agent=agent, message=agent.messages[1])  # Output added
     assert next(events) == AfterInvocationEvent(agent=agent)
 
-    assert len(agent.messages) == 0  # no new messages added
+    assert len(agent.messages) == 2  # prompt and structured output added