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 What to Load Eagerly
  • 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
• ON-DEMAND-CAPABILITIES.md
• TOOLS-CORE.md
• NATIVE-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, then consider whether `defer_loading=True` should be the default
└── 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 What to Load Eagerly

Is this part of a capability?
├── Yes → First consider `defer_loading=True`; would eager loading improve most turns or be required for hooks/settings?
│   ├── Yes → Keep it eager in an always-on capability
│   └── No → Use capabilities on demand with `defer_loading=True`
└── No → Will this information/tool schema improve most model turns?
    ├── Yes → Keep it eager in the base agent or hot-path toolset
    └── No → Is it a named workflow with instructions plus tools?
        ├── Yes → Use capabilities on demand with `defer_loading=True`
        └── No → Is it one of many individually discoverable tools?
            ├── Yes → Use tool-level `defer_loading=True` and ToolSearch
            └── No → Can the caller fetch it outside the agent and pass only the relevant slice?
                ├── Yes → Keep it out of the agent; inject the slice through deps, prompt, or retrieval
                └── No → Reconsider whether the agent actually needs this context

Be opinionated here. Any capability should at least be evaluated for deferral; eager loading is a choice to justify, not the unexamined default. Pydantic AI agents should not carry large optional policy text, rarely used schemas, or specialist runbooks in the eager prompt just because they are available. Prefer progressive disclosure unless the information is genuinely universal.

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:, moonshotai:. For any other OpenAI-compatible endpoint, point OpenAIChatModel at it with provider=OpenAIProvider(base_url=..., api_key=...). For anything that isn't OpenAI-compatible, subclass Model.

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: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