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

zastrowm · 2025-09-30T14:22:21Z

src/strands/output/modes.py

+        return True  # All our models support function calling
+
+
+class NativeMode(OutputMode):


Are we planning on implementing any of this? If not then I think we should discard these until we've proved that how they can be implemented; IMHO during implementation we could determine that the signature needs to be changed and if we shipped it, we're stuck with it as-is

Good point. I'll keep the mode we're using and remove the others (maybe just leave a comment as to what they can be)

I comment this elsewhere, but I think we can just remove mode for now until we decide if/when we want it

I removed all the other modes except for the ToolMode. You think we should get rid of this concept of mode altogether? I think that may make it challenging to move fast and add a Native mode etc. Because we'll have to then introduce this concept. What is/are the downsides and concerns with just having out ToolMode? For example, how does us worse off than having some kind of other implementation that is specific to tools?

Agree with skipping mode for now. I think it helps us move faster by shipping less code for now.

Im a bit concerned that adding mode will be a bit more information than what the customer really needs right now. They want to invoke an agent and get structured output. They can build different modes if they really want to. If we hear from customers that they really want to have mode, we can add that later.

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

src/strands/types/_events.py

zastrowm · 2025-09-30T14:28:36Z

tests/strands/tools/test_structured_output.py

 from pydantic import BaseModel, Field

-from strands.tools.structured_output import convert_pydantic_to_tool_spec
+from strands.tools.structured_output.structured_output_utils import convert_pydantic_to_tool_spec


I think this move would be a breaking change no?

hmmm. I't really an internal helper tool for the sdk (even though it's not prefixed with _). are concerned customers are using and will continue using the old import?

In the past, anything that doesn't have _ we've maintained backwards compatibility for

Thus why everything should be private unless we have a reason to make it public

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

Unshure · 2025-09-30T16:58:22Z

src/strands/agent/agent.py


-    def __call__(self, prompt: AgentInput = None, **kwargs: Any) -> AgentResult:
+    def __call__(
+        self, prompt: AgentInput = None, structured_output_type: Optional[Type[BaseModel]] = None, **kwargs: Any


Chatted offline about this, but lets add support for invocation_state first before adding this new field: #919

Also, we need to include a * to ensure backwards compatibility

Suggested change

self, prompt: AgentInput = None, structured_output_type: Optional[Type[BaseModel]] = None, **kwargs: Any

self, prompt: AgentInput = None, *, structured_output_type:Type[BaseModel] | None = None, **kwargs: Any

Unshure · 2025-09-30T16:58:43Z

src/strands/agent/agent.py


-    async def invoke_async(self, prompt: AgentInput = None, **kwargs: Any) -> AgentResult:
+    async def invoke_async(
+        self, prompt: AgentInput = None, structured_output_type: Optional[Type[BaseModel]] = None, **kwargs: Any


Suggested change

self, prompt: AgentInput = None, structured_output_type: Optional[Type[BaseModel]] = None, **kwargs: Any

self, prompt: AgentInput = None, *, structured_output_type:Type[BaseModel] | None = None, **kwargs: Any

Unshure · 2025-09-30T20:48:53Z

src/strands/output/utils.py

lets try not to name files or directories utils. Can we come up with a more specific name for what this does?

gotcha. what's the aversion to naming it utils is it because it's too generic? Because in this case I'm kinda using the path to imply it's utility output.utils

utils end up being dumping grounds for unrelated functionality, so it's effectively banned; it usually makes sense in a better name module/file. In this case, I think this could live in OutputSchema

makes sense!

Unshure · 2025-09-30T20:49:59Z

src/strands/tools/structured_output/structured_output_utils.py

nit: dont name directories or files utils

Unshure · 2025-09-30T20:50:50Z

src/strands/tools/structured_output/README.md

Can we have a more concise readme here? I dont think this needs to be so verbose

Yes! Once I add tests i will reduce the readme scope

Unshure · 2025-09-30T20:57:02Z

src/strands/tools/structured_output/structured_output_tool.py

+
+            # Store in invocation state with namespaced key
+            key = f"{BASE_KEY}_{tool_use_id}"
+            invocation_state[key] = validated_object


We should not be using invocation_state as part of the sdk. This is customer information that we should not touch.

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

afarntrog · 2025-10-01T15:05:43Z

src/strands/event_loop/event_loop.py

    attributes = {"event_loop_cycle_id": str(invocation_state.get("event_loop_cycle_id"))}
    cycle_start_time, cycle_trace = agent.event_loop_metrics.start_cycle(attributes=attributes)
    invocation_state["event_loop_cycle_trace"] = cycle_trace
+    output_schema: OutputSchema = invocation_state.get("output_schema")


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.

afarntrog · 2025-10-01T15:18:15Z

src/strands/tools/executors/_executor.py

        cycle_trace: Trace,
        cycle_span: Any,
        invocation_state: dict[str, Any],
+        **kwargs: Any,


@zastrowm @Unshure The goal over here is to pass the structured_output_context to the tool executor _execute.
I'm curious to get your thoughts if you think it's better to use kwargs (like i'm doing here) or is it better to make it an explicit param?

Make it explicit; never use kwargs for silently passing things; it's a PITA to understand and trace down (thus our stricter rules about it 😄 )

This is also private and thus not necessary to maintain backwards compatibility

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

src/strands/agent/agent.py


-    def __call__(self, prompt: AgentInput = None, **kwargs: Any) -> AgentResult:
+    def __call__(
+        self, prompt: AgentInput = None, structured_output_model: Optional[Type[BaseModel]] = None, **kwargs: Any


nit: Switch to union types Type[BaseModel] | None

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?

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

zastrowm · 2025-10-01T17:14:31Z

src/strands/output/modes.py

+    from strands.types.tools import ToolSpec
+
+
+class ToolMode(OutputMode):


Along the lines of YAGNI, If this is the only mode, I'd ditch it for now;

I think all of this could be inlined into Structured_output_context for now

zastrowm · 2025-10-01T17:34:43Z

src/strands/output/utils.py

utils end up being dumping grounds for unrelated functionality, so it's effectively banned; it usually makes sense in a better name module/file. In this case, I think this could live in OutputSchema

zastrowm · 2025-10-01T18:49:43Z

src/strands/output/modes.py

+        return True  # All our models support function calling
+
+
+class NativeMode(OutputMode):


I comment this elsewhere, but I think we can just remove mode for now until we decide if/when we want it

zastrowm · 2025-10-01T18:51:25Z

src/strands/event_loop/event_loop.py

+    # Force structured output tool call if LLM didn't use it automatically
+    if structured_output_context and structured_output_context.output_schema and stop_reason == "end_turn":
+        if not structured_output_context.can_retry():
+            logger.warning(


I think this should be a throw case? Let's throw for now and we can lighten later if we decide that's not desirable.

But for now I'd say "If we said it has to be structured_output and it ends up not being structured_output, we should make the user aware of that"

hmmm. I can hear that. I think this comes back to what you mentioned to me earlier how we can consider a structured_output_config in the future and something like this can be configured. Although, I would push back a bit on raising an error to be the default as users may desire structured output but settle on the text output when it's not feasible. I would like to reason through some more use cases as for now I can hear both sides.

Can we raise an exception that captures that additional information. If our structured output feature did not produce structured output, that feels like an error. If someone wants to do something with that, they can catch the error and then handle it. An exception feels more explicit.

zastrowm · 2025-10-01T18:52:40Z

src/strands/event_loop/event_loop.py

+    if structured_output_context and structured_output_context.output_schema:
+        if structured_output_result := structured_output_context.extract_result(tool_uses):
+            yield StructuredOutputEvent(structured_output=structured_output_result)
+            invocation_state["request_state"]["stop_event_loop"] = True


My gut says that we should figure out how to do this without using stop_event_loop; is that possible?

If we do do this, then can StructuredOutputTool do this instead?

My gut says that we should figure out how to do this without using stop_event_loop; is that possible?

Yes! I actually had an initial way to do it w/o this but I found this to be cleaner because we need "less" code. With that said here is my alternate way:
We simply set a field in the structured_output_context to stop - such as structured_output_context.end_loop.

Then we just add that check like so (updated or condition) here:

if ( invocation_state["request_state"].get("stop_event_loop", False) or structured_output_context.end_loop ): agent.event_loop_metrics.end_cycle(cycle_start_time, cycle_trace) yield EventLoopStopEvent( stop_reason, message, agent.event_loop_metrics, invocation_state["request_state"], structured_output_result ) return

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?

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

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

		return True # All our models support function calling


		class NativeMode(OutputMode):

	self, prompt: AgentInput = None, structured_output_type: Optional[Type[BaseModel]] = None, **kwargs: Any
	self, prompt: AgentInput = None, , structured_output_type:Type[BaseModel] \| None = None, *kwargs: Any

		from strands.types.tools import ToolSpec


		class ToolMode(OutputMode):

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!

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

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!

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!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

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!

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!

afarntrog commented Sep 29, 2025 •

edited

Loading

zastrowm Sep 30, 2025 •

edited

Loading

afarntrog Sep 30, 2025 •

edited

Loading

zastrowm commented Sep 30, 2025 •

edited

Loading