feat: Add Structured Output as part of the agent loop #943

afarntrog · 2025-09-29T20:36:02Z

Description

This PR implements a comprehensive structured output system that allows agents to return validated Pydantic models. Strands developers can pass in the structured_output_model field, set to a Pydantic model, when initializing an agent or when invoking the agent. The agent will attempt to populate the pydantic object and set it to a field, structured_output, that can be accessed from the AgentResult object. Callers can use different pydantic models per invocation, or the same, or for some invocations use structured_output_model and for others ignore it.

Examples

Structured Output on the agent invocation

from strands import Agent
from pydantic import BaseModel

class UserProfile(BaseModel):
    """Basic user profile model."""
    name: str
    age: int
    occupation: str

agent = Agent()
agent_res = agent(
    "Create a profile for John Doe who is a 25 year old dentist",
    structured_output_model=UserProfile
)
>>> agent_res.structured_output
UserProfile(name='John Doe', age=25, occupation='dentist')

Structured Output when initializing the agent

from strands import Agent
from pydantic import BaseModel

class UserProfile(BaseModel):
    """Basic user profile model."""
    name: str
    age: int
    occupation: str

agent = Agent(structured_output_model=UserProfile)
agent_res = agent("Create a profile for John Doe who is a 25 year old dentist")
>>> agent_res.structured_output
UserProfile(name='John Doe', age=25, occupation='dentist')

See the README.md for more examples.

Key Features:

• structured_output_model parameter support in Agent class and call method
• Complete output module with base classes, modes, and utilities (src/strands/output/)
• Tool-based system with automatic retry logic
• Enhanced event loop integration for structured output processing and validation
• Comprehensive documentation with examples, use cases, and best practices
• Type safety with full typing support and Pydantic validation
• Backward compatibility with existing tool ecosystem

ℹ️ NOTE: ℹ️

In the interest of moving fast I did not add tests yet. I will add those once team is aligned on the approach. I did create a comprehensive README.md that can be used to run tests locally.
Also, see the model provider section at the end of the readme.md to view the models this was tested against and the results. The Writer model is not currently working when I use other tools along with Structured output but structured output itself works.

API-Bar raising

structured_output_model is the parameter name we agreed to
StructuredOutputEvent we added a new Typed Event called StructuredOutputEvent

Open questions:

feat: Add Structured Output as part of the agent loop #943 (comment)
- Options: Possibly just pass in the tool name as the msg or we can consider using gettext but that would be hard to scale

Related Issues

Documentation PR

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• [ ] I ran hatch run prepare

Checklist

• [ ] I have read the CONTRIBUTING document
• [ ] I have added any necessary tests that prove my fix is effective or my feature works
• [ ] I have updated the documentation accordingly
• [ ] I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• [ ] My changes generate no new warnings
• [ ] Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

feat: Implement comprehensive structured output system This feature addition introduces a complete structured output system that allows agents to return validated Pydantic models instead of raw text responses, providing type safety and consistency for AI agent interactions. ## Key Features Added ### Core Structured Output System - **New output module**: Complete structured output architecture with base classes, modes, and utilities - **Agent integration**: Native structured_output_type parameter support in Agent class and __call__ method - **Event loop integration**: Enhanced event loop to handle structured output processing and validation - **Tool-based fallback**: Automatic fallback mechanism using structured output tools when native support unavailable ### Architecture Components - **OutputMode base class**: Abstract interface for different structured output implementations - **ToolMode implementation**: Tool-based structured output mode with caching and retry logic - **OutputSchema resolution**: Centralized schema resolution utility with BASE_KEY constant - **Structured output handler**: Comprehensive handler with logging, caching, and error handling ### Developer Experience - **PydanticAI-style interface**: Familiar API pattern for structured output specification - **Comprehensive documentation**: 400+ line README with examples, use cases, and best practices - **Type safety**: Full typing support with proper generic types and validation - **Streaming compatibility**: Works seamlessly with existing streaming functionality ### Tool Integration - **Structured output tool**: Dedicated tool for handling structured output requests - **Registry integration**: Enhanced tool registry to support structured output tools - **Backward compatibility**: Maintains compatibility with existing tool ecosystem ## Technical Implementation ### Files Added - `src/strands/output/`: Complete output module with base classes, modes, and utilities - `src/strands/tools/structured_output/`: Dedicated structured output tool implementation - `src/strands/types/output.py`: Type definitions for output system - Comprehensive documentation and examples ### Files Modified - Enhanced Agent class with structured_output_type parameter and default schema support - Updated event loop for structured output processing and validation - Improved AgentResult to include structured_output field - Model provider updates for structured output compatibility ### Key Improvements - **Error handling**: Robust error handling with fallback mechanisms - **Performance**: Caching system for improved performance with repeated schema usage - **Logging**: Enhanced logging for debugging and monitoring structured output operations - **Code quality**: Comprehensive formatting, linting, and style improvements ## Usage Examples python # Basic structured output from strands import Agent from pydantic import BaseModel class UserProfile(BaseModel): name: str age: int occupation: str agent = Agent() result = agent("Create a profile for John, 25, dentist", structured_output_type=UserProfile) profile = result.structured_output # Validated UserProfile instance ## Migration Notes - Existing agents continue to work without changes - New structured_output_type parameter is optional - Legacy output modes are deprecated but still functional Resolves: Multiple structured output related issues

Add explicit user message instructing the agent to format previous response as structured output during forced structured output attempts.

src/strands/agent/agent.py

src/strands/output/modes.py

zastrowm · 2025-09-30T14:27:43Z

src/strands/tools/registry.py

        tools: List[ToolSpec] = [tool_spec for tool_spec in all_tools.values()]
        return tools

+    def register_dynamic_tool(self, tool: AgentTool) -> None:


I'm not sure we should be adding/removing the tool dynamically - can we simply append the tool_spec inside of the event_loop?

Hmm. I'm not opposed but to better understand, what is the downside? Are we concerned that others will use this method to dynamically register tools? Or is it something else? Wouldn't appending the tool_spec basically be dynamically adding but without a method? (There does seem to be a specific self.dynamic_tools variable. When is that supposed to be used?

IMHO, it's better to be functional (don't modify state unless you have to) as it's side-effect free. In this case, you always have to remember to unregister even in exceptional cases and while reading the code, you need to remember that something is temporarily added.

Are we even calling unregister_dynamic_tool right now?

I'm open to being wrong about this, but it feels... odd

Hmmm. You're making an interesting point with the register/deregister "mental overhead". I do like how it has more of a 'native' feel when it's part of the toolbox - even though we add it dynamically. Lemme see if there's a better way to add to the tools we provide the model w/o the dynamic register. I can probably just do something like tool_specs = existing tool specs + SO tool spec or something

I looked into this a bit more. I see we need the tool in registry as it's accessed here:

sdk-python/src/strands/tools/executors/_executor.py

Line 60 in 776fd93

tool_info = agent.tool_registry.dynamic_tools.get(tool_name)

If we add it in the event loop like so and don't register it:

. . . tool_specs = agent.tool_registry.get_all_tool_specs() + so_tool_specs try: async for event in stream_messages( agent.model, agent.system_prompt, agent.messages, tool_specs, structured_output_context.tool_choice ): . . .

it does not make it to the registry and will result in a tool_name=<UserProfile>, available_tools=<[]> | tool not found in registry exception when it reaches the

sdk-python/src/strands/tools/executors/_executor.py

Line 31 in 776fd93

async def _stream(

method

src/strands/types/_events.py

tests/strands/tools/test_structured_output.py

src/strands/agent/agent_result.py

zastrowm · 2025-09-30T15:37:02Z

I think we'd block the new structured_output change (#919) on whether or not someone is using kwargs vs invocation_state. That is, if you're using structured_output and you're trying to pass additional features, then you must be using invocation_state and not kwargs - this pushes folks towards invocation_state and I think is the most backwards compatible

agent.invoke_async(output_model=Person, additional_arg=some_value) # does not use structured_output
agent.invoke_async(output_model=Person, invocation_state={"additional_arg": some_value}) # uses structured_output

src/strands/agent/agent.py

src/strands/output/utils.py

src/strands/tools/structured_output/structured_output_utils.py

src/strands/tools/structured_output/README.md

src/strands/tools/structured_output/structured_output_tool.py

Replace StructuredOutputHandler with StructuredOutputContext to provide better encapsulation and cleaner separation of concerns. This change: - Introduces StructuredOutputContext to manage structured output state - Updates Agent and event loop to use the new context-based approach - Modifies tool executors to work with the context pattern - Removes the handler-based implementation in favor of context

- Replace mode.get_tool_specs() calls with cached tool_specs property - Improve code formatting and add trailing commas

Rename parameter throughout codebase for better clarity. This change improves API consistency and makes the parameter's purpose more explicit.

Simplify output mode options by removing unused NativeMode and PromptMode implementations, keeping only ToolMode for structured output. This reduces complexity while maintaining full functionality through the tool-based approach.

src/strands/agent/agent.py

afarntrog · 2025-10-01T14:42:13Z

src/strands/agent/agent_result.py

    message: Message
    metrics: EventLoopMetrics
    state: Any
+    structured_output: Optional[BaseModel] = None


In the future we plan on allowing for more types than BaseModel however I think it's best to set the type then. It probably won't be any but more like a very large set of types that we would extract out to StructuredOutputType

src/strands/agent/agent_result.py

src/strands/event_loop/event_loop.py

afarntrog · 2025-10-01T15:06:13Z

src/strands/event_loop/event_loop.py

+        )
+        agent.messages.append({
+            "role": "user", 
+            "content": [{"text": "You must format the previous response as structured output."}]


Good point. hmmm

afarntrog · 2025-10-01T15:08:08Z

src/strands/event_loop/event_loop.py

+        forced_invocation_state["tool_choice"] = {"any": {}}
+        forced_invocation_state["_structured_output_only"] = True
+
+        events = recurse_event_loop(agent=agent, invocation_state=forced_invocation_state)


(this code has been slightly updated but I think you're question is beyond the updates).
Are you asking why recurse and not call the model.structured_output? It's because we our using the Tool based approach and if the model didn't call it on it's own, we will pass in only the StructuredOutputTool and then recurse the event loop so the model calls it on it's own.

src/strands/tools/executors/_executor.py

src/strands/agent/agent.py

zastrowm · 2025-10-01T17:12:57Z

src/strands/agent/agent.py

                - list[ContentBlock]: Multi-modal content blocks
                - list[Message]: Complete messages with roles
                - None: Use existing conversation history
+            structured_output_model: Pydantic model type(s) for structured output (overrides agent default).


Is there a way to pass None if you don't want structured output? Should that be an option?

Just ignore it and it'll use the default None. The user can also set structured_output_model=None as well

zastrowm · 2025-10-01T17:13:20Z

src/strands/agent/agent.py

+    @deprecated(
+        "Agent.structured_output method is deprecated."
+        " You should pass in `structured_output_model` directly into the agent invocation."
+        " see the <LINK> for more details"


TODO - update LINK

src/strands/output/modes.py

src/strands/output/utils.py

src/strands/output/modes.py

src/strands/event_loop/event_loop.py

zastrowm · 2025-10-01T18:55:45Z

src/strands/tools/structured_output/structured_output_context.py

+    - Tracking expected tool names from output schemas
+    - Managing validated result storage
+    - Extracting structured output results from tool executions
+    - Managing retry attempts for structured output forcing


In what case does retrying take effect and when it's useful? If it's a tool-call, what can cause the LLM to fail the tool call?

So I think for the models like Writer that don't accept tool choice the model can fail to call the tool

zastrowm · 2025-10-01T18:56:44Z

src/strands/tools/registry.py

        tools: List[ToolSpec] = [tool_spec for tool_spec in all_tools.values()]
        return tools

+    def register_dynamic_tool(self, tool: AgentTool) -> None:


I'm open to being wrong about this, but it feels... odd

…xt explicitly - Delete output module (OutputSchema, ToolMode, utils) - Replace OutputSchema with direct tool based usage throughout - Update StructuredOutputContext to work without OutputSchema wrapper - Simplify structured output handling in agent and tool executors - Plumb the StructuredOutputContext explicitly instead of kwargs This simplifies the codebase by removing an unnecessary abstraction layer and using Pydantic models directly for structured output configuration.

Replace Optional[Type[BaseModel]] with Type[BaseModel] | None across agent, event_loop, and structured_output modules for consistency with Python 3.10+ type hint syntax.

- Replace structured_output_model checks with is_enabled property - Raise StructuredOutputException when retry limit exceeded instead of silent failure - cleanup

- Add public API exports for convert_pydantic_to_tool_spec - Replace Any with BaseModel type hints for structured output - Simplify condition checks using is_enabled property - Clean up module docstrings and comments

afarntrog and others added 3 commits September 29, 2025 14:41

Add user instruction message when forcing structured output

dceb617

Add explicit user message instructing the agent to format previous response as structured output during forced structured output attempts.

add readme with model provider examples

75a0ce7

afarntrog temporarily deployed to auto-approve September 29, 2025 20:36 — with GitHub Actions Inactive

rm output file extra

b543cec

afarntrog temporarily deployed to auto-approve September 29, 2025 20:38 — with GitHub Actions Inactive

rm lock file

099e70a

afarntrog temporarily deployed to auto-approve September 29, 2025 20:39 — with GitHub Actions Inactive

afarntrog requested review from zastrowm and Unshure September 29, 2025 20:39

update readme

882fcd6

afarntrog temporarily deployed to auto-approve September 29, 2025 20:44 — with GitHub Actions Inactive

afarntrog marked this pull request as ready for review September 30, 2025 13:59

zastrowm requested changes Sep 30, 2025

View reviewed changes

zastrowm changed the title ~~Strucuted output 891 pr~~ Structured output Sep 30, 2025

Unshure reviewed Sep 30, 2025

View reviewed changes

afarntrog added 2 commits September 30, 2025 17:27

make instance variable

4979771

afarntrog temporarily deployed to auto-approve September 30, 2025 21:33 — with GitHub Actions Inactive

Refactor structured output to use cached tool_specs property

b9f9456

- Replace mode.get_tool_specs() calls with cached tool_specs property - Improve code formatting and add trailing commas

afarntrog temporarily deployed to auto-approve October 1, 2025 13:45 — with GitHub Actions Inactive

Refactor: Rename structured_output_type to structured_output_model

36bd507

Rename parameter throughout codebase for better clarity. This change improves API consistency and makes the parameter's purpose more explicit.

afarntrog had a problem deploying to auto-approve October 1, 2025 14:01 — with GitHub Actions Failure

afarntrog changed the title ~~Structured output~~ feat: Add Structured Output as part of the agent loop Oct 1, 2025

Remove NativeMode and PromptMode output classes

dba8828

Simplify output mode options by removing unused NativeMode and PromptMode implementations, keeping only ToolMode for structured output. This reduces complexity while maintaining full functionality through the tool-based approach.

afarntrog temporarily deployed to auto-approve October 1, 2025 14:21 — with GitHub Actions Inactive

afarntrog added 2 commits October 1, 2025 10:47

cleanup

fb274ac

cleanup

dcc6ac4

afarntrog temporarily deployed to auto-approve October 1, 2025 15:09 — with GitHub Actions Inactive

afarntrog commented Oct 1, 2025

View reviewed changes

use model instead of type

45dd56b

afarntrog had a problem deploying to auto-approve October 1, 2025 15:19 — with GitHub Actions Failure

afarntrog requested review from zastrowm and Unshure October 1, 2025 15:39

zastrowm requested changes Oct 1, 2025

View reviewed changes

afarntrog added 7 commits October 3, 2025 15:49

Update type hints to use modern union syntax

9003fdd

Replace Optional[Type[BaseModel]] with Type[BaseModel] | None across agent, event_loop, and structured_output modules for consistency with Python 3.10+ type hint syntax.

hatch fmt --formatter

7b192a1

Refactor structured output handling and improve error reporting

89ea3c6

- Replace structured_output_model checks with is_enabled property - Raise StructuredOutputException when retry limit exceeded instead of silent failure - cleanup

Change structured_output_context default to empty instance

247e9c4

cleanup

eeb97be

cleanup

8f5ffad

afarntrog had a problem deploying to auto-approve October 6, 2025 02:23 — with GitHub Actions Failure

Refactor structured_output module and improve type safety

a42171c

- Add public API exports for convert_pydantic_to_tool_spec - Replace Any with BaseModel type hints for structured output - Simplify condition checks using is_enabled property - Clean up module docstrings and comments

afarntrog had a problem deploying to auto-approve October 6, 2025 15:25 — with GitHub Actions Failure

afarntrog requested a review from zastrowm October 6, 2025 16:55

Make structured output context optional and update formatting

cfb39f5

afarntrog temporarily deployed to auto-approve October 6, 2025 21:02 — with GitHub Actions Inactive

feat: Add Structured Output as part of the agent loop #943

Are you sure you want to change the base?

feat: Add Structured Output as part of the agent loop #943

Uh oh!

Conversation

afarntrog commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Examples

Structured Output on the agent invocation

Structured Output when initializing the agent

Key Features:

API-Bar raising

Open questions:

Related Issues

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zastrowm commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

afarntrog commented Sep 29, 2025 •

edited

Loading

zastrowm commented Sep 30, 2025 •

edited

Loading