# pydantic/pydantic-ai architecture

> Architecture diagram of the GitHub repository pydantic/pydantic-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pydantic/pydantic-ai
- Repository: https://github.com/pydantic/pydantic-ai

## Overview

Pydantic AI is a typed Python SDK for running model-backed agents across terminal, web, realtime voice, durable execution, and direct APIs. The principal workflow is: an application submits a prompt to an agent, the runtime prepares model requests, dispatches model-selected tools, validates structured output, and returns or streams typed results. Model/provider adapters, toolsets, capabilities, and deferred approvals extend that loop. Image generation and embeddings are sibling APIs; Pydantic Graph and Pydantic Evals are separate workspace packages. The map reflects documented capabilities plus sampled implementation points; unsampled integrations are shown only at directory level.

Main entry points: [`pydantic_ai_slim/pydantic_ai/tool_manager.py`](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/tool_manager.py) (Tool Manager), [`pydantic_ai_slim/pydantic_ai/agent/abstract.py`](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/agent/abstract.py) (Agent API), [`pydantic_ai_slim/pydantic_ai/run.py`](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/run.py) (Run Engine), [`pydantic_ai_slim/pydantic_ai/providers`](https://github.com/pydantic/pydantic-ai/tree/main/pydantic_ai_slim/pydantic_ai/providers) (Provider Adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_realtime_sessions["Realtime Sessions<br/>[_session.py]"]
  node_web_ui["Web UI Adapter<br/>[app.py]"]
  node_cli["CLI Interface<br/>[web.py]"]
end

subgraph group_runtime["Agent Runtime"]
  node_agent_api["Agent API<br/>[abstract.py]"]
  node_run_engine["Run Engine<br/>[run.py]"]
  node_message_parts["Message Parts<br/>[_parts_manager.py]"]
  node_output_validation["Typed Output<br/>[_output.py]"]
end

subgraph group_extensions["Tools And Capabilities"]
  node_tool_manager["Tool Manager<br/>[tool_manager.py]"]
  node_toolsets["Toolsets<br/>[abstract.py]"]
  node_tool_search["Tool Search<br/>[_tool_search.py]"]
  node_capabilities["Capabilities<br/>[abstract.py]"]
  node_deferred_handler["Deferred Handler"]
  node_durable_execution["Durable Execution"]
end

subgraph group_providers["Models And Media"]
  node_model_api["Model API<br/>[_abstract.py]"]
  node_provider_adapters["Provider Adapters"]
  node_openrouter["OpenRouter Provider<br/>[openrouter.py]"]
  node_vllm["vLLM Provider<br/>[vllm.py]"]
  node_image_api["Image Generation<br/>[base.py]"]
  node_embedding_api["Embeddings<br/>[base.py]"]
end

subgraph group_packages["Workspace Packages"]
  node_graph_package["Typed Graphs"]
  node_evals_package["Agent Evaluations"]
  node_judge_evaluator["LLM Judge<br/>[llm_as_a_judge.py]"]
end

node_application(("Application User"))
node_llm_services["Model Services"]
node_durable_backends["Durable Backends"]

node_application -->|"submits prompt"| node_agent_api
node_agent_api -->|"starts run"| node_run_engine
node_run_engine -->|"requests model"| node_model_api
node_run_engine -->|"dispatches tools"| node_tool_manager
node_tool_manager -->|"resolves tools"| node_toolsets
node_tool_manager -->|"handles approvals"| node_deferred_handler
node_tool_manager -->|"discovers tools"| node_tool_search
node_capabilities -->|"wraps execution"| node_tool_manager
node_run_engine -->|"updates stream"| node_message_parts
node_message_parts -->|"forms output"| node_output_validation
node_model_api -->|"uses provider"| node_provider_adapters
node_provider_adapters -->|"calls models"| node_llm_services
node_openrouter -.->|"calls gateway"| node_llm_services
node_vllm -.->|"calls endpoint"| node_llm_services
node_output_validation -->|"returns result"| node_application
node_web_ui -->|"adapts requests"| node_agent_api
node_cli -->|"starts agent"| node_agent_api
node_realtime_sessions -->|"streams audio"| node_model_api
node_durable_execution -.->|"persists operations"| node_durable_backends
node_image_api -->|"selects provider"| node_provider_adapters
node_embedding_api -->|"selects provider"| node_provider_adapters
node_judge_evaluator -->|"runs judge"| node_agent_api
node_graph_package -->|"provides control flow"| node_application

click node_agent_api "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/agent/abstract.py"
click node_run_engine "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/run.py"
click node_message_parts "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_parts_manager.py"
click node_output_validation "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_output.py"
click node_tool_manager "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/tool_manager.py"
click node_toolsets "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/toolsets/abstract.py"
click node_tool_search "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/toolsets/_tool_search.py"
click node_capabilities "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/capabilities/abstract.py"
click node_deferred_handler "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/capabilities/deferred_tool_handler.py"
click node_durable_execution "https://github.com/pydantic/pydantic-ai/tree/main/pydantic_ai_slim/pydantic_ai/durable_exec"
click node_model_api "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/models/_abstract.py"
click node_provider_adapters "https://github.com/pydantic/pydantic-ai/tree/main/pydantic_ai_slim/pydantic_ai/providers"
click node_openrouter "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/providers/openrouter.py"
click node_vllm "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/providers/vllm.py"
click node_realtime_sessions "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/realtime/_session.py"
click node_web_ui "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/ui/_web/app.py"
click node_cli "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_cli/web.py"
click node_image_api "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/images/base.py"
click node_embedding_api "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/embeddings/base.py"
click node_graph_package "https://github.com/pydantic/pydantic-ai/tree/main/pydantic_graph/pydantic_graph"
click node_evals_package "https://github.com/pydantic/pydantic-ai/tree/main/pydantic_evals/pydantic_evals"
click node_judge_evaluator "https://github.com/pydantic/pydantic-ai/blob/main/pydantic_evals/pydantic_evals/evaluators/llm_as_a_judge.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_realtime_sessions,node_web_ui,node_cli,node_application toneBlue
class node_agent_api,node_run_engine,node_message_parts,node_output_validation toneAmber
class node_tool_manager,node_toolsets,node_tool_search,node_capabilities,node_deferred_handler,node_durable_execution toneMint
class node_model_api,node_provider_adapters,node_openrouter,node_vllm,node_image_api,node_embedding_api toneRose
class node_graph_package,node_evals_package,node_judge_evaluator,node_llm_services,node_durable_backends toneIndigo
```

## Components

### User Interfaces

- [Realtime Sessions](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/realtime/_session.py): `pydantic_ai_slim/pydantic_ai/realtime/_session.py`
- [Web UI Adapter](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/ui/_web/app.py): `pydantic_ai_slim/pydantic_ai/ui/_web/app.py`
- [CLI Interface](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_cli/web.py): `pydantic_ai_slim/pydantic_ai/_cli/web.py`

### Agent Runtime

- [Agent API](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/agent/abstract.py): `pydantic_ai_slim/pydantic_ai/agent/abstract.py`
- [Run Engine](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/run.py): `pydantic_ai_slim/pydantic_ai/run.py`
- [Message Parts](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_parts_manager.py): `pydantic_ai_slim/pydantic_ai/_parts_manager.py`
- [Typed Output](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_output.py): `pydantic_ai_slim/pydantic_ai/_output.py`

### Tools And Capabilities

- [Tool Manager](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/tool_manager.py): `pydantic_ai_slim/pydantic_ai/tool_manager.py`
- [Toolsets](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/toolsets/abstract.py): `pydantic_ai_slim/pydantic_ai/toolsets/abstract.py`
- [Tool Search](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/toolsets/_tool_search.py): `pydantic_ai_slim/pydantic_ai/toolsets/_tool_search.py`
- [Capabilities](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/capabilities/abstract.py): `pydantic_ai_slim/pydantic_ai/capabilities/abstract.py`
- [Deferred Handler](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/capabilities/deferred_tool_handler.py): `pydantic_ai_slim/pydantic_ai/capabilities/deferred_tool_handler.py`
- [Durable Execution](https://github.com/pydantic/pydantic-ai/tree/main/pydantic_ai_slim/pydantic_ai/durable_exec): `pydantic_ai_slim/pydantic_ai/durable_exec`

### Models And Media

- [Model API](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/models/_abstract.py): `pydantic_ai_slim/pydantic_ai/models/_abstract.py`
- [Provider Adapters](https://github.com/pydantic/pydantic-ai/tree/main/pydantic_ai_slim/pydantic_ai/providers): `pydantic_ai_slim/pydantic_ai/providers`
- [OpenRouter Provider](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/providers/openrouter.py): `pydantic_ai_slim/pydantic_ai/providers/openrouter.py`
- [vLLM Provider](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/providers/vllm.py): `pydantic_ai_slim/pydantic_ai/providers/vllm.py`
- [Image Generation](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/images/base.py): `pydantic_ai_slim/pydantic_ai/images/base.py`
- [Embeddings](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/embeddings/base.py): `pydantic_ai_slim/pydantic_ai/embeddings/base.py`

### Workspace Packages

- [Typed Graphs](https://github.com/pydantic/pydantic-ai/tree/main/pydantic_graph/pydantic_graph): `pydantic_graph/pydantic_graph`
- [Agent Evaluations](https://github.com/pydantic/pydantic-ai/tree/main/pydantic_evals/pydantic_evals): `pydantic_evals/pydantic_evals`
- [LLM Judge](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_evals/pydantic_evals/evaluators/llm_as_a_judge.py): `pydantic_evals/pydantic_evals/evaluators/llm_as_a_judge.py`

### Other components

- **Application User**
- **Model Services**
- **Durable Backends**

## Connections

- Application User → Agent API: submits prompt
- Agent API → Run Engine: starts run
- Run Engine → Model API: requests model
- Run Engine → Tool Manager: dispatches tools
- Tool Manager → Toolsets: resolves tools
- Tool Manager → Deferred Handler: handles approvals
- Tool Manager → Tool Search: discovers tools
- Capabilities → Tool Manager: wraps execution
- Run Engine → Message Parts: updates stream
- Message Parts → Typed Output: forms output
- Model API → Provider Adapters: uses provider
- Provider Adapters → Model Services: calls models
- OpenRouter Provider → Model Services: calls gateway
- vLLM Provider → Model Services: calls endpoint
- Typed Output → Application User: returns result
- Web UI Adapter → Agent API: adapts requests
- CLI Interface → Agent API: starts agent
- Realtime Sessions → Model API: streams audio
- Durable Execution → Durable Backends: persists operations
- Image Generation → Provider Adapters: selects provider
- Embeddings → Provider Adapters: selects provider
- LLM Judge → Agent API: runs judge
- Typed Graphs → Application User: provides control flow
