Defining Agent Output Schemas with Pydantic Models

Constrain an agent's final response to a typed Pydantic model so callers receive validated data instead of free text.

Summary

Set Pydantic AI's output_type (or Instructor's response_model) to a BaseModel that encodes the fields, enums, and validators your application will act on.

Recipe

1. List the fields a machine consumer needs (not every phrase the model might say).
2. Model them as a Pydantic BaseModel with types, Field(description=...), and enums for closed sets.
3. Add validators for business rules that JSON Schema alone cannot express (cross-field checks, allowlists).
4. Pass the model as output_type on Agent (Pydantic AI) or response_model (Instructor).
5. Prefer default tool-style structured output unless you need NativeOutput or PromptedOutput for a specific model.
6. Run once on golden examples, then tighten optional vs required fields based on real failure rates.
7. Version the schema when consumers depend on it; treat breaking field renames like API breaks.

Working Example

from enum import Enum
 
from pydantic import BaseModel, Field, field_validator
from pydantic_ai import Agent
 
 
class Severity(str, Enum):
    info = "info"
    warning = "warning"
    critical = "critical"
 
 
class IncidentTicket(BaseModel):
    """Final structured ticket the agent must return."""
 
    title: str = Field(description="Short title for the incident board")
    severity: Severity
    affected_service: str
    summary: str = Field(description="What happened and impact, 2-4 sentences")
    next_actions: list[str] = Field(
        min_length=1,
        description="Concrete next steps for the on-call engineer",
    )
    page_oncall: bool = Field(
        description="True only if severity is critical or customer impact is active"
    )
 
    @field_validator("title")
    @classmethod
    def title_not_empty(cls, v: str) -> str:
        v = v.strip()
        if len(v) < 5:
            raise ValueError("title must be at least 5 characters")
        return v
 
 
agent = Agent(
    "openai:gpt-4o-mini",  # verify at build
    output_type=IncidentTicket,
    instructions=(
        "You are an incident triage agent. "
        "Return only fields needed for the ticket system."
    ),
)
 
result = agent.run_sync(
    "Payments API p99 latency is 4s for 12 minutes; checkout errors elevated."
)
ticket = result.output
print(ticket.severity, ticket.page_oncall)
print(ticket.model_dump_json(indent=2))

Callers never parse markdown bullets. They import IncidentTicket and type-check against result.output.

Deep Dive

What belongs in the schema

Include fields that drive:

• routing or severity
• tool selection or follow-up actions
• persistence and analytics
• UI binding (forms, badges, tables)

Exclude:

• chain-of-thought narration
• redundant natural-language restatements of structured fields
• unstable free-form keys ("extra notes" bags that become junk drawers)

Output modes in Pydantic AI

Start with the default tool output path. Switch modes when a model cannot mix tools and native structured output, or when evals show better reliability for your schema.

Unions and multiple final shapes

When the agent may return different shapes (success vs need-more-info), use a list or union of models:

from pydantic import BaseModel
from pydantic_ai import Agent
 
 
class Ready(BaseModel):
    answer: str
 
 
class NeedInfo(BaseModel):
    question: str
 
 
agent = Agent(
    "openai:gpt-4o-mini",
    output_type=[Ready, NeedInfo],
    instructions="If data is incomplete, return NeedInfo instead of guessing.",
)

Each member becomes its own output tool by default, which often improves accuracy versus one giant optional-field model.

Field descriptions are part of the prompt

Models read JSON Schema descriptions. Write them as operator instructions ("ISO-8601 date", "use service catalog names"), not as internal comments.

Sharing schemas with Instructor

The same BaseModel can back:

• Pydantic AI output_type=IncidentTicket
• Instructor response_model=IncidentTicket

Keep domain models in a shared module so extraction jobs and agents do not drift.

Streaming structured output

Pydantic AI can stream partial structured objects with partial validation. Only treat the final validated object as commit-ready for side effects.

Gotchas

1. Optional everything hides failures. If every field is optional, almost any JSON "validates" and your contract is empty.
2. Mega-schemas raise retry rates. Split into smaller outputs or multi-step agents when models thrash.
3. Enums must match product language. Mismatched labels (sev1 vs critical) cause avoidable validation loops.
4. Native structured + tools is model-dependent. Some providers forbid combining them; verify for your model.
5. Validators need clear errors. Vague ValueError("invalid") does not teach the model how to repair.
6. Docstrings matter. Model and field docs are model-facing documentation, not only developer docs.
7. str in output unions changes stop behavior. Including plain text makes free-text a valid final result; use deliberately.

Alternatives

FAQs

Related

• Pydantic AI & Instructor Basics - first structured runs
• Why Structured Output Matters More as Agents Get Autonomous - why contracts matter
• Handling Validation Failures and Retry Loops Gracefully - repair loops
• Type-Safe Tool Definitions with Pydantic AI - tool arg schemas
• Using Instructor for Schema-Constrained Outputs Across Providers - extraction-focused path
• Pydantic AI & Instructor Best Practices - design checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.