How pydantic/pydantic-ai works
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: tool_manager.py Tool Manager · abstract.py Agent API · run.py Run Engine · providers Provider Adapters
Components 25
User Interfaces
- Realtime Sessions
pydantic_ai_slim/pydantic_ai/realtime/_session.py - Web UI Adapter
pydantic_ai_slim/pydantic_ai/ui/_web/app.py - CLI Interface
pydantic_ai_slim/pydantic_ai/_cli/web.py
Agent Runtime
- Agent API
pydantic_ai_slim/pydantic_ai/agent/abstract.py - Run Engine
pydantic_ai_slim/pydantic_ai/run.py - Message Parts
pydantic_ai_slim/pydantic_ai/_parts_manager.py - Typed Output
pydantic_ai_slim/pydantic_ai/_output.py
Tools And Capabilities
- Tool Manager
pydantic_ai_slim/pydantic_ai/tool_manager.py - Toolsets
pydantic_ai_slim/pydantic_ai/toolsets/abstract.py - Tool Search
pydantic_ai_slim/pydantic_ai/toolsets/_tool_search.py - Capabilities
pydantic_ai_slim/pydantic_ai/capabilities/abstract.py - Deferred Handler
pydantic_ai_slim/pydantic_ai/capabilities/deferred_tool_handler.py - Durable Execution
pydantic_ai_slim/pydantic_ai/durable_exec
Models And Media
- Model API
pydantic_ai_slim/pydantic_ai/models/_abstract.py - Provider Adapters
pydantic_ai_slim/pydantic_ai/providers - OpenRouter Provider
pydantic_ai_slim/pydantic_ai/providers/openrouter.py - vLLM Provider
pydantic_ai_slim/pydantic_ai/providers/vllm.py - Image Generation
pydantic_ai_slim/pydantic_ai/images/base.py - Embeddings
pydantic_ai_slim/pydantic_ai/embeddings/base.py
Workspace Packages
- Typed Graphs
pydantic_graph/pydantic_graph - Agent Evaluations
pydantic_evals/pydantic_evals - LLM Judge
pydantic_evals/pydantic_evals/evaluators/llm_as_a_judge.py
Other components
- Application User
- Model Services
- Durable Backends
Connections 23
- 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