feat: Add Structured Output as part of the agent loop

[afarntrog]

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

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

• [x] I ran hatch run prepare

Checklist

• [x] I have read the CONTRIBUTING document
• [x] 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
• [x] 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.

[dbschmigelski]

.

outdated

[afarntrog]

#1026