agents.structured.agent¶

Structured output agent implementation.

This module provides the StructuredOutputAgent that converts any agent’s output into structured formats using Pydantic models and tool-based extraction.

Classes¶

StructuredOutputAgent

Agent that converts any input into structured output.

Functions¶

create_structured_agent(output_model[, name, ...])

Factory function to create a structured output agent.

Module Contents¶

class agents.structured.agent.StructuredOutputAgent¶

Bases: SimpleAgentV3

Agent that converts any input into structured output.

This agent specializes in taking unstructured text (typically from another agent’s output) and converting it into a well-defined Pydantic model structure. It always uses tool-based structured output (v2) for reliable extraction.

The agent can be used in multi-agent workflows where you need to: - Convert free-form agent responses into structured data - Extract specific fields from complex outputs - Ensure type-safe data flow between agents - Create consistent output formats across different agent types

Examples

Basic usage with generic output:

agent = StructuredOutputAgent(
    name="structurer",
    output_model=GenericStructuredOutput
)
result = agent.run("Some unstructured text...")

Custom output model:

class CustomOutput(BaseModel):
    title: str
    points: List[str]
    score: float

agent = StructuredOutputAgent(
    name="custom_structurer",
    output_model=CustomOutput,
    custom_context="Focus on extracting title and scoring"
)

In multi-agent workflow:

# Any agent produces unstructured output
react_agent = ReactAgent(name="analyzer", ...)

# StructuredOutputAgent converts it
structurer = StructuredOutputAgent(
    name="structurer",
    output_model=AnalysisOutput
)

# Add both to workflow
agents = [react_agent, structurer]

extract_from_messages(messages)¶

Extract structured output from a list of messages.

This is useful when processing conversation history or multiple agent outputs.

Parameters:: messages (list) – List of messages to process
Returns:: Structured output matching the output_model
Return type:: Any

extract_from_state(state)¶

Extract structured output from agent state.

This is useful in multi-agent workflows where you need to structure another agent’s output from the shared state.

Parameters:: state (Any) – Agent state containing messages
Returns:: Structured output matching the output_model
Return type:: Any

model_post_init(__context)¶

Initialize the agent after Pydantic initialization.

Parameters:: __context (Any)
Return type:: None

agents.structured.agent.create_structured_agent(output_model, name='structured_output', temperature=0.1, custom_context=None, **kwargs)¶

Factory function to create a structured output agent.

This is a convenience function for creating structured agents with common configurations.

Parameters:

output_model (type[pydantic.BaseModel]) – The Pydantic model for output structure
name (str) – Agent name (defaults to “structured_output”)
temperature (float) – LLM temperature (defaults to 0.1 for consistency)
custom_context (str | None) – Additional extraction context
**kwargs – Additional arguments passed to StructuredOutputAgent

Returns:

Configured StructuredOutputAgent

Return type:

StructuredOutputAgent

Examples

Basic creation:

agent = create_structured_agent(
    output_model=TaskOutput,
    name="task_structurer"
)

With custom context:

agent = create_structured_agent(
    output_model=GenericStructuredOutput,
    custom_context="Focus on technical details",
    temperature=0.2
)