19-structured-output

Structured Output with Strands Agents

This tutorial teaches you how to get reliable, typed, validated data from your Strands agents using structured output. Instead of parsing free-form text, you define a Pydantic model and the agent returns a validated Python object — ready for downstream code, APIs, and workflows.

Overview

The core idea is simple: you give the agent a prompt and a Pydantic model describing the shape you want, and you get back a validated, typed object instead of free-form text.

Under the hood, the SDK registers your model as a dynamic tool, the LLM calls it to produce the data, and Pydantic validates the result — retrying automatically if validation fails. See How It Works for the full mechanics.

Tutorial Details

Information	Details
Strands Features	Structured Output, Pydantic Validation, Tool Integration
Agent Pattern	Single agent with structured output
Tools	calculator (from strands-agents-tools)
Model	Claude Sonnet 4.5 on Amazon Bedrock

How It Works

1. Developer defines a Pydantic BaseModel describing the desired output schema
2. The model is passed to the agent via structured_output_model=MyModel
3. The SDK converts the Pydantic model into a tool specification and registers it as a dynamic tool
4. The LLM processes the prompt, optionally using regular tools to gather information
5. The LLM calls the structured output tool with data matching the schema
6. Pydantic validates the output — on failure, the error is sent back and the LLM self-corrects
7. On success, the validated object is available at result.structured_output

Prerequisites

• Python 3.10 or later
• AWS account with Amazon Bedrock model access configured
• Model access enabled for Claude Sonnet 4.5
• Basic understanding of Python and Pydantic
• Familiarity with Strands Agents basics (see Tutorial 01)

Tutorial Structure

19-structured-output/
├── README.md
├── requirements.txt
└── structured-output.ipynb

File	Description
structured-output.ipynb	Interactive notebook covering the core structured output patterns

What You'll Learn

• Your First Structured Output: Define a flat Pydantic model, pass it to an agent, and access typed results — both sync and async
• Complex Schemas: Build nested models with List, Optional, field validators, and enum constraints
• Validation & Self-Correction: Watch the automatic retry loop fire when validation fails, inspect the retry trail in agent.messages, handle StructuredOutputException, and customize the forcing prompt
• Tools + Structured Output: Combine regular tools with structured output so agents can gather data and return structured results

Installation

Install the required dependencies:

pip install -r requirements.txt

Running the Examples

1. Open the notebook: structured-output.ipynb
2. Run cells sequentially — each section builds on the previous one
3. Observe the agent's structured output in each example

Note: The exact field values will vary between runs since the LLM generates content dynamically. The structure and types will always match your Pydantic model.

Key Concepts

• Structured Output: A feature that makes agents return validated Pydantic objects instead of free-form text
• structured_output_model: The parameter (on Agent constructor or per-call) that specifies the Pydantic model to use
• Structured Output Tool: A dynamic tool the SDK auto-registers from your Pydantic model — the LLM calls it to produce structured data
• Validation & Self-Correction: When the LLM's output fails Pydantic validation, the SDK sends the error back and the LLM retries automatically
• Forcing: If the LLM ignores the structured output tool, the SDK forces it by restricting available tools and setting tool_choice
• StructuredOutputException: Raised when the LLM fails to produce valid structured output even after forcing
• structured_output_prompt: A customizable message sent to the LLM when forcing is triggered

Additional Resources

• Strands Agents Documentation
• Structured Output User Guide
• Pydantic Documentation
• Strands Tools Repository

Next Steps

• Learn about Memory to persist agent memory across sessions
• Explore Agents as Tools to compose structured output agents into larger systems
• Try Graph Workflows to build multi-step pipelines with structured data flowing between nodes