/building-pydantic-ai-agents

Architecture and Decision Guide

Detailed decision trees, comparison tables, and architecture overview for Pydantic AI.

Contents

• Task-Family References
• Decision Trees
  • Choosing a Tool Registration Method
  • Choosing an Output Mode
  • Choosing a Multi-Agent Pattern
  • Choosing How to Extend Agent Behavior
  • Choosing a Capability
  • Choosing a Testing Approach
• Comparison Tables
  • Output Mode Comparison
  • Model Provider Prefixes
  • Tool Decorator Comparison
  • Built-in Capabilities
  • When to Use Each Agent Method
• Architecture Overview

Task-Family References

Use this file for comparisons and abstraction choices.

If the user already knows what they want to do, load the narrower task guide instead:

• AGENTS-CORE.md
• CAPABILITIES-AND-HOOKS.md
• TOOLS-CORE.md
• BUILTIN-TOOLS.md
• TOOLS-ADVANCED.md
• INPUT-AND-HISTORY.md
• TESTING-AND-DEBUGGING.md
• ORCHESTRATION-AND-INTEGRATIONS.md

Decision Trees

Choosing a Tool Registration Method

Need RunContext (deps, usage, messages)?
├── Yes → Use @agent.tool
└── No → Pure function, no context needed?
    ├── Yes → Use @agent.tool_plain
    └── Tools defined outside agent file?
        ├── Yes → Use tools=[Tool(...)] in constructor
        └── Dynamic tools based on context?
            ├── Yes → Use ToolPrepareFunc
            └── Multiple related tools as a group?
                └── Yes → Use FunctionToolset

Choosing an Output Mode

Need structured data with Pydantic validation?
├── Yes → Does provider support native JSON mode?
│   ├── Yes, and you want it → Use NativeOutput(MyModel)
│   └── No, or prefer consistency → Use ToolOutput(MyModel) [default]
└── No → Need custom parsing logic?
    ├── Yes → Use TextOutput(parser_fn)
    └── No → Just plain text?
        └── Yes → Use output_type=str [default]

Dynamic schema at runtime?
└── Yes → Use StructuredDict(json_schema)

Choosing a Multi-Agent Pattern

Child agent returns result to parent?
├── Yes → Use agent delegation via tools
└── No → Permanent hand-off to specialist?
    ├── Yes → Use output functions
    └── Application code between agents?
        ├── Yes → Use programmatic hand-off
        └── Complex state machine?
            └── Yes → Use Graph-based control

Choosing How to Extend Agent Behavior

Need reusable behavior across agents (tools + hooks + instructions)?
├── Yes → Build a custom capability (subclass AbstractCapability)
└── No → Just intercepting lifecycle events?
    ├── Yes → Complex interception needing tools/instructions too?
    │   ├── Yes → Subclass AbstractCapability
    │   └── No → Use Hooks capability with decorators
    └── No → Defining agents from config files?
        ├── Yes → Use Agent.from_file() with YAML/JSON specs
        └── No → Just adding tools?
            ├── Yes → Use @agent.tool or Toolset
            └── Pass args directly to Agent constructor

Choosing a Capability

Need model thinking/reasoning?
├── Yes → Use Thinking(effort='high')
└── Need web search?
    ├── Yes → Use WebSearch() (auto-fallback to local)
    └── Need URL fetching?
        ├── Yes → Use WebFetch()
        └── Need MCP servers?
            ├── Yes → Use MCP()
            └── Need lifecycle hooks only?
                ├── Yes → Use Hooks()
                └── Need to filter/modify tool defs per step?
                    └── Yes → Use PrepareTools()

Choosing a Testing Approach

Need deterministic, fast tests?
├── Yes → Use TestModel with agent.override()
└── Need specific tool call behavior?
    ├── Yes → Use FunctionModel
    └── Testing against real API (integration)?
        └── Yes → Use pytest-recording with VCR cassettes

Comparison Tables

Output Mode Comparison

Model Provider Prefixes

Additional prefixes: litellm:, nebius:, ovhcloud:, alibaba:, sambanova:, vercel:, outlines:, moonshotai:. For truly custom providers, subclass Model or use OpenAIChatModel with a custom base_url.

Tool Decorator Comparison

Built-in Capabilities

When to Use Each Agent Method

See Run Methods and Streaming for event_stream_handler details.

Architecture Overview

Agent execution flow: Agent.run() → UserPromptNode → ModelRequestNode → CallToolsNode → (loop or end)

Key generic types:

• Agent[AgentDepsT, OutputDataT] — dependency type + output type
• RunContext[AgentDepsT] — available in tools and system prompts
• AbstractCapability[AgentDepsT] — base class for reusable behavior bundles

Agent construction:

• Python: Agent(model, instructions=..., tools=..., capabilities=...)
• Declarative: Agent.from_file('agent.yaml') or Agent.from_spec({...})

Capabilities are the primary extension point — they bundle tools, lifecycle hooks, instructions, and model settings into reusable units. Built-in capabilities include Thinking, WebSearch, WebFetch, Hooks, MCP, and more.

Lifecycle hooks (via Hooks or AbstractCapability) intercept every stage: before_run → before_model_request → before_tool_execute → after_tool_execute → after_model_request → after_run

Model string format: "provider:model-name" (e.g., "openai:gpt-5.2", "anthropic:claude-sonnet-4-6", "google-gla:gemini-3-pro-preview")

Output modes:

• ToolOutput — structured data via tool calls (default for Pydantic models)
• NativeOutput — provider-specific structured output
• PromptedOutput — prompt-based structured extraction
• TextOutput — plain text responses