Skip to main content
Instead of answering in natural language, the agent can return a specific output structure using Pydantic models.

​
Why Using Structured Output?

Using structured output ensures your agents return predictable, type-safe responses. This approach:
  • Automatically validates and parses responses
  • Guarantees all required fields are present and correctly typed
  • Reduces ambiguity compared to natural-language answers
By defining schemas upfront, you can trust that your agent’s output will always match your expectations.

​
Usage

  1. Define the desired output schema using a Pydantic Model.
  2. Pass that model to the agent’s output_model parameter.
  3. The agent will always return responses that conform to the schema.
For example, here’s a schema for a chef assistant agent: 
from pydantic import BaseModel, Field

class Ingredient(BaseModel):
    name: str = Field(..., description="Name of the ingredient")
    amount: float = Field(..., description="Amount of the ingredient")
    unit: str = Field(..., description="Unit of the ingredient")

class Recipe(BaseModel):
    ingredients: list[Ingredient] = Field(..., description="List of ingredients")
    total_time: float = Field(..., description="Total time in minutes")
    steps: list[str] = Field(..., description="Steps to follow")

agent = Agent(
    name="output_model_agent",
    model="openai/gpt-4o-mini",
    output_model=Recipe)

await agent(prompt="I want to make lasagna").collect()

​
Output Example

The response will strictly follow the Recipe structure: 
{
  "ingredients": [
    {
      "name": "Egg yolks",
      "amount": 6,
      "unit": "pieces"
    },
    {
      "name": "Granulated sugar",
      "amount": 150,
      "unit": "grams"
    },
    {
      "name": "Mascarpone cheese",
      "amount": 500,
      "unit": "grams"
    },
    {
      "name": "Heavy cream",
      "amount": 250,
      "unit": "ml"
    },
    {
      "name": "Strong brewed coffee (cooled)",
      "amount": 300,
      "unit": "ml"
    },
    {
      "name": "Ladyfinger biscuits",
      "amount": 300,
      "unit": "grams"
    },
    {
      "name": "Unsweetened cocoa powder",
      "amount": 2,
      "unit": "tbsp"
    }
  ],
  "total_time": "40 minutes",
  "steps": [
    "Whisk egg yolks and sugar together until thick and pale.",
    "Fold in mascarpone cheese until smooth.",
    "Whip heavy cream to stiff peaks and gently fold into mascarpone mixture.",
    "Dip ladyfinger biscuits briefly in brewed coffee and arrange in a single layer in a dish.",
    "Spread half of the mascarpone cream mixture over the biscuits.",
    "Add another layer of dipped ladyfingers and top with remaining cream.",
    "Dust generously with cocoa powder.",
    "Refrigerate at least 4 hours (preferably overnight) before serving."
  ]
}