feat: add structured output support using Pydantic models

- Add  method to Agent class for handling structured outputs
- Create structured_output.py utility for converting Pydantic models to tool specs
- Improve error handling when extracting model_id from configuration
- Add integration tests to validate structured output functionality

src/strands/agent/agent.py

@@ -16,10 +16,11 @@
 import random
 from concurrent.futures import ThreadPoolExecutor
 from threading import Thread
-from typing import Any, AsyncIterator, Callable, Dict, List, Mapping, Optional, Union
+from typing import Any, AsyncIterator, Callable, Dict, List, Mapping, Optional, Type, Union
 from uuid import uuid4
 
 from opentelemetry import trace
+from pydantic import BaseModel
 
 from ..event_loop.event_loop import event_loop_cycle
 from ..handlers.callback_handler import CompositeCallbackHandler, PrintingCallbackHandler, null_callback_handler
@@ -328,7 +329,15 @@ def __call__(self, prompt: str, **kwargs: Any) -> AgentResult:
                 - metrics: Performance metrics from the event loop
                 - state: The final state of the event loop
         """
-        model_id = self.model.config.get("model_id") if hasattr(self.model, "config") else None
+        # Safely get model_id if available
+        model_id = None
+        try:
+            config = getattr(self.model, "config", None)
+            if isinstance(config, dict):
+                model_id = config.get("model_id")
+        except Exception:
+            # Ignore any errors accessing model configuration
+            pass
 
         self.trace_span = self.tracer.start_agent_span(
             prompt=prompt,
@@ -353,6 +362,73 @@ def __call__(self, prompt: str, **kwargs: Any) -> AgentResult:
             # Re-raise the exception to preserve original behavior
             raise
 
+    def with_output(self, prompt: str, output_model: Type[BaseModel]) -> BaseModel:
+        """Set the output model for the agent.
+
+        Args:
+            prompt: The prompt to use for the agent.
+            output_model: The output model to use for the agent.
+
+        Returns: the loaded basemodel
+        """
+        from ..tools.structured_output import convert_pydantic_to_bedrock_tool
+
+        # Convert the pydantic basemodel to a tool spec
+        tool_spec = convert_pydantic_to_bedrock_tool(output_model)
+
+        # Create a dynamic tool name to avoid collisions
+        tool_name = f"generate_{output_model.__name__}"
+        tool_spec["toolSpec"]["name"] = tool_name
+
+        # Register the tool with the tool registry
+        # We need a special type of tool that just passes through the input
+        from ..tools.tools import PythonAgentTool
+
+        # Create a passthrough callback that just returns the input
+        # with the signature expected by PythonAgentTool
+        from ..types.tools import ToolResult, ToolUse
+
+        def output_callback(
+            tool_use: ToolUse, model: Any = None, messages: Optional[dict[str, Any]] = None, **kwargs: Any
+        ) -> ToolResult:
+            # Return the ToolResult explicitly typed
+            result: ToolResult = {
+                "toolUseId": tool_use["toolUseId"],
+                "status": "success",
+                "content": [{"text": "Output generated successfully"}],
+            }
+            return result
+
+        # Register the tool
+        from ..types.tools import ToolResult, ToolUse
+
+        tool = PythonAgentTool(tool_name=tool_name, tool_spec=tool_spec["toolSpec"], callback=output_callback)
+        self.tool_registry.register_tool(tool)
+
+        # Call the model with the tool and get the response
+        # This will run the model and invoke the tool
+        self(prompt)
+
+        # Extract the tool input from the message
+        # Find the first toolUse in the conversation history
+        tool_input = None
+        for message in self.messages:
+            if message.get("role") == "assistant":
+                for content in message.get("content", []):
+                    if isinstance(content, dict) and "toolUse" in content:
+                        tool_use = content["toolUse"]
+                        if tool_use.get("name") == tool_name:
+                            tool_input = tool_use.get("input", {})
+                            break
+                if tool_input:
+                    break
+
+        # Create the output model from the tool input and return it
+        if not tool_input:
+            raise ValueError(f"Model did not generate a valid {output_model.__name__}")
+
+        return output_model(**tool_input)
+
     async def stream_async(self, prompt: str, **kwargs: Any) -> AsyncIterator[Any]:
         """Process a natural language prompt and yield events as an async iterator.
 
@@ -367,7 +443,7 @@ async def stream_async(self, prompt: str, **kwargs: Any) -> AsyncIterator[Any]:
 
         Returns:
             An async iterator that yields events. Each event is a dictionary containing
-            information about the current state of processing, such as:
+            invocation about the current state of processing, such as:
             - data: Text content being generated
             - complete: Whether this is the final chunk
             - current_tool_use: Information about tools being executed