Pydantic AI is an open-source Python agent framework from the team behind the Pydantic validation library, designed for building production applications on top of large language models with type safety and validated structured output. Among AI frameworks & tools, it occupies the space between raw provider SDKs and heavier orchestration libraries such as LangChain: it gives developers an Agent abstraction, typed tools and dependency injection while keeping ordinary Python control flow.
The framework treats an LLM call the way a well-designed web framework treats an HTTP request. Inputs, dependencies and outputs have declared Python types, the model’s responses are validated against Pydantic models, and invalid responses trigger automatic retries instead of silently propagating malformed data into the application.
How Pydantic AI structures an agent
A Pydantic AI agent is a reusable object that bundles a model choice, instructions, tools and an output type into one typed unit. The developer creates an Agent once, usually at module level, and then calls it many times with different user prompts and dependencies, much as a FastAPI application defines routes once and serves many requests.
At run time, the agent sends the system prompt and user message to the model, receives either text or tool call requests, executes the requested Python functions, returns their results to the model and repeats until the model produces a final answer. That final answer is then parsed and validated against the declared output type before the call returns.
The following table summarizes the core building blocks and the role each plays in a run.
| Component | What it defines | Typical form |
|---|---|---|
| Model | Which LLM provider and model answers | A string such as openai:gpt-4o or a model object |
| Instructions | Static or dynamic system guidance | String argument or decorated function |
| Dependencies | Runtime resources the agent may use | A dataclass declared through deps_type |
| Tools | Python functions the model may call | Functions decorated with @agent.tool |
| Output type | Shape of the validated final answer | A Pydantic model, dataclass or primitive type |
| Run context | Access to dependencies inside tools | A typed RunContext parameter |
Type safety, validation and dependency injection
The defining feature of Pydantic AI is that types flow through the whole agent. When an agent is declared with deps_type=SupportDeps and output_type=Ticket, static type checkers such as mypy and Pyright can verify that tools receive the right dependency object and that result.output is a Ticket, catching many integration errors before the code runs.
Structured output works by exposing the output schema to the model, typically as a special tool whose arguments match the JSON Schema of the declared type. When the model returns arguments that fail validation, the framework sends the validation errors back to the model and asks it to try again, up to a configurable retry limit. Tools can raise ModelRetry to trigger the same corrective loop for business-rule failures.
Dependency injection replaces global state. Database connections, HTTP clients, API keys and user identities are passed into agent.run() as a deps object and reach tools through RunContext. This keeps agents testable and reusable, because a test can supply a fake database without patching module globals.
Model support, observability and testing
Pydantic AI is model-agnostic: the same agent code can target OpenAI, Anthropic, Google Gemini, Mistral, Groq, Cohere, Amazon Bedrock and OpenAI-compatible endpoints such as local Ollama servers. Switching providers usually means changing one model identifier, although prompts and tool designs may still need tuning because model behavior differs across vendors.
Operational features are designed for production rather than notebooks. The table below lists the capabilities most teams evaluate first.
| Feature | Purpose | Practical effect |
|---|---|---|
| Streaming | Deliver partial text or partial structured output | Lower perceived latency in user interfaces |
| Usage limits | Cap requests and tokens per run | Prevents runaway tool loops and cost spikes |
| OpenTelemetry tracing | Export spans for each model and tool call | Works with Logfire or other OTel backends |
| TestModel and FunctionModel | Replace real LLM calls in tests | Fast, deterministic unit tests without API cost |
| MCP client support | Connect to Model Context Protocol servers | Reuse external tool servers without custom code |
| Pydantic Graph | Typed state machines for multi-step workflows | Explicit control over complex agent flows |
The built-in test models deserve emphasis. TestModel automatically calls every tool and generates schema-valid output, while FunctionModel lets a test script the exact responses, so teams can test control flow without network calls or flaky model outputs.
How Pydantic AI compares with related frameworks
Pydantic AI is best understood as a lightweight, typed agent layer rather than a complete orchestration ecosystem. It overlaps with several neighboring tools in the same category, but each makes different design trade-offs.
| Framework | Primary design focus | Main trade-off |
|---|---|---|
| Pydantic AI | Type-safe agents with validated output | Fewer prebuilt integrations than larger ecosystems |
| LangChain | Broad catalog of integrations and chains | More abstraction layers to learn and debug |
| LangGraph | Graph-based, stateful multi-agent workflows | More setup for simple single-agent tasks |
| CrewAI | Role-based teams of collaborating agents | Less fine-grained control of each call |
| OpenAI Agents SDK | Agents, handoffs and guardrails for one vendor | Strongest fit with OpenAI models |
| DSPy | Programmatic prompt optimization | Different mental model from direct agent code |
Teams that already use FastAPI and Pydantic often find the learning curve short, because the same idioms apply. Teams that need dozens of ready-made document loaders or vector store connectors may combine Pydantic AI with a retrieval library such as LlamaIndex rather than expecting the framework to supply them.
Choosing and applying Pydantic AI
Pydantic AI fits best when reliable structured data matters more than conversational breadth. The decision table below maps common situations to a recommended approach.
| Situation | Recommended approach | Reason |
|---|---|---|
| Extracting fields from documents | Agent with a Pydantic output model | Validation and retries enforce the schema |
| Support bot calling internal APIs | Agent with typed tools and deps | Injected clients keep tools testable |
| Long multi-step business process | Pydantic Graph or durable execution | Explicit state survives failures and restarts |
| Single prompt with free-text reply | Provider SDK or minimal agent | A framework adds little value here |
| Large catalog of prebuilt connectors | Combine with an integration-rich library | Pydantic AI keeps its core small |
A sound practice is to keep output models small and specific. Deeply nested schemas with many optional fields raise the chance of validation failures and retries, which increase both latency and token cost.
Limitations and common mistakes
Validation guarantees structural correctness, not factual correctness. A response can match the schema perfectly and still contain an invented invoice number, so business checks and evaluation remain necessary.
- Unbounded retries on difficult schemas multiply cost; set retry and usage limits deliberately.
- Overly permissive tools give the model actions it should not take; scope each tool narrowly and validate its arguments.
- Assuming provider parity leads to surprises, because tool calling and structured output quality vary between models.
- Skipping tracing makes multi-step failures hard to diagnose; instrument agents from the first deployment.
- Pinning nothing in a fast-moving library invites breaking changes; lock versions and read release notes before upgrading.
In plain words
Pydantic AI is a toolkit that helps programmers build AI assistants in Python that return tidy, checked information instead of loose text. The programmer describes what a correct answer must look like. It might need a name, a date and an amount. The framework then checks every answer against that description.
Sometimes the AI gets the format wrong. The framework then sends the answer back with a note about the mistake. It works much like a clerk returning a form with a missing field. The result is software that breaks less often because bad data is caught at the door.
A real-world example
An accounts payable team at a mid-sized logistics company receives about 3,000 supplier invoices per month as PDF attachments. A developer builds a Pydantic AI agent whose output type is an Invoice model with supplier name, VAT number, invoice date, currency, line items and total, plus a validator that checks that line items add up to the stated total.
The agent receives each extracted text, calls a tool that looks up the supplier in the company’s ERP system through an injected database client, and returns a validated Invoice object. When totals do not match, the validator raises an error, the model gets a second attempt, and persistent mismatches go to a human review queue.
After a month of operation, the team reports that most invoices post without manual typing, while the remaining exceptions arrive already flagged with the precise field that failed. Unit tests written with TestModel run in seconds in the continuous integration pipeline, so schema changes no longer break production unnoticed.