Pydantic AI

On this page 8

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.

ComponentWhat it definesTypical form
ModelWhich LLM provider and model answersA string such as openai:gpt-4o or a model object
InstructionsStatic or dynamic system guidanceString argument or decorated function
DependenciesRuntime resources the agent may useA dataclass declared through deps_type
ToolsPython functions the model may callFunctions decorated with @agent.tool
Output typeShape of the validated final answerA Pydantic model, dataclass or primitive type
Run contextAccess to dependencies inside toolsA typed RunContext parameter
Core components of a Pydantic AI agent

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.

FeaturePurposePractical effect
StreamingDeliver partial text or partial structured outputLower perceived latency in user interfaces
Usage limitsCap requests and tokens per runPrevents runaway tool loops and cost spikes
OpenTelemetry tracingExport spans for each model and tool callWorks with Logfire or other OTel backends
TestModel and FunctionModelReplace real LLM calls in testsFast, deterministic unit tests without API cost
MCP client supportConnect to Model Context Protocol serversReuse external tool servers without custom code
Pydantic GraphTyped state machines for multi-step workflowsExplicit control over complex agent flows
Production-oriented features and their purpose

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.

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.

FrameworkPrimary design focusMain trade-off
Pydantic AIType-safe agents with validated outputFewer prebuilt integrations than larger ecosystems
LangChainBroad catalog of integrations and chainsMore abstraction layers to learn and debug
LangGraphGraph-based, stateful multi-agent workflowsMore setup for simple single-agent tasks
CrewAIRole-based teams of collaborating agentsLess fine-grained control of each call
OpenAI Agents SDKAgents, handoffs and guardrails for one vendorStrongest fit with OpenAI models
DSPyProgrammatic prompt optimizationDifferent mental model from direct agent code
Pydantic AI and neighboring agent frameworks

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.

SituationRecommended approachReason
Extracting fields from documentsAgent with a Pydantic output modelValidation and retries enforce the schema
Support bot calling internal APIsAgent with typed tools and depsInjected clients keep tools testable
Long multi-step business processPydantic Graph or durable executionExplicit state survives failures and restarts
Single prompt with free-text replyProvider SDK or minimal agentA framework adds little value here
Large catalog of prebuilt connectorsCombine with an integration-rich libraryPydantic AI keeps its core small
When to use Pydantic AI

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.