Pydantic already sits underneath a large slice of the Python AI stack. The OpenAI SDK depends on it, FastAPI depends on it, and most teams reach for it the moment they need to turn unpredictable model output into something a program can actually consume. So when the Pydantic team shipped their own agent framework in late 2024, the surprise wasn’t that it validated schemas cleanly. It was that the entire agent loop finally felt as boring and predictable as the rest of the library.
PydanticAI is that framework. It aims at the same audience FastAPI won over: Python developers who want strong typing, sensible defaults, and code they can unit test without spinning up a cluster.
FastAPI ergonomics, pointed at language models
The core object is an Agent, and you configure it roughly the way you’d configure a route. You pass a model string with a provider prefix, declare the shape of the final answer, and attach tools with decorators. A weather agent might be built with a model string like openai:gpt-4o, a result type pointing at a WeatherReport model, a system prompt, and one tool registered through the @agent.tool decorator.
Swapping providers is then a one-line change. Point the same agent at anthropic:claude-sonnet-4-0, google-gla:gemini-2.0-flash, groq:llama-3.3-70b, or a local Ollama model and everything else stays where it is. That matters more than it sounds. Teams benchmarking three models on a real task usually end up with a tangle of provider-specific glue code. Here, the glue is a string.
Tools are just functions
Tool schemas get generated from the Python signature and docstring, so the model sees accurate parameter descriptions without you hand-writing JSON. Type hints on arguments are enforced, which catches a lot of silent breakage before it reaches production. There’s also a plain variant for tools that don’t need the run context, handy for pure lookups like currency conversion or a simple database read.
Structured output is the whole point
Give the agent a Pydantic model as its result type and every response arrives as a validated instance of that model. Lists of enums stay enums. Optional fields stay optional. Date strings parse into date objects.
What makes this more than a parsing trick is the failure path. When the model returns something that doesn’t validate, PydanticAI doesn’t hand you an exception and shrug. It sends the validation error back along with a request to fix it, up to a configurable retry count. Most schema misses resolve on the second attempt, and you can watch each retry in your traces.
The trade-off is latency and tokens. A retry is another full model call, so a badly designed schema with deep nesting, ambiguous field names, and no examples in the field descriptions becomes a quiet cost multiplier. Field descriptions do most of the heavy lifting here.
Dependency injection that makes agents testable
Every run carries a RunContext, which holds your own dependencies: a database connection, an API client, the current user, a feature flag service. Tools read from it directly, and because it’s typed, your editor knows what’s available at each call site.
The payoff shows up in testing. PydanticAI ships a TestModel and a FunctionModel that let you run an agent end to end with no network calls, swapping in deterministic responses and asserting on the tool calls that were made. Paired with pydantic-evals, you can keep a set of cases with expected outputs and run them in CI like any other suite.
That’s the difference between demo code and code that survives a refactor. Most agent frameworks ask you to trust that a prompt change didn’t break anything. This one lets you prove it.
Tools, MCP, and multi-step workflows
Beyond decorated functions, PydanticAI speaks the Model Context Protocol, so an agent can pull in MCP servers for filesystem access, GitHub, or internal systems without bespoke integration code. For anything needing deterministic control flow rather than vibes, there’s Pydantic Graph, a small state machine library where nodes are functions and edges are typed transitions. Agents can sit inside a graph as nodes, which is a cleaner answer to complex orchestration than prompting a model to decide the next step indefinitely.
Observability, Logfire, and OpenTelemetry
Instrumentation is built in rather than bolted on. Each run produces OpenTelemetry spans for model requests, tool calls, and validation retries, and the team’s own Logfire service renders them neatly. You can point the same traces at any OTel backend. When you’re debugging a multi-tool agent that occasionally picks the wrong function at step four, this is the feature that saves the afternoon.
How it sits next to LangChain, LlamaIndex, and CrewAI
These tools overlap, but they aren’t interchangeable.
- LangChain and LangGraph offer the widest integration surface and a mature graph runtime, at the cost of many layers between your code and the model.
- LlamaIndex shines when retrieval is the hard part: chunking, indexes, reranking, hybrid search.
- CrewAI is built around role-based teams of agents and reads naturally when your problem genuinely looks like a crew of specialists.
- PydanticAI stays closest to plain Python, with fewer abstractions, strict types, and a codebase you can read in an afternoon.
Plenty of teams mix them. Using LlamaIndex for retrieval and PydanticAI for the typed agent layer on top is a reasonable split, and nothing in the framework fights you for doing it.
Getting an agent in front of users
Framework choice is the easy part. Streaming a partial response into a UI, syncing conversation state between client and server, and letting a person interrupt a running agent are product problems the library won’t solve for you. Tooling around app-native agents is moving quickly, and projects like CopilotKit, which raised $27M to help developers deploy app-native AI agents, exist precisely to handle that layer between the runtime and the interface. Worth knowing where the boundary sits before you start building on either side of it.
Rough edges worth planning for
A few things to budget for. Docs are decent, but the ecosystem is younger than LangChain’s, so obscure questions mean reading source. Releases have moved fast, so pin versions in production. Streaming structured output is inherently harder than streaming text, since partial JSON isn’t valid until it’s finished. And retries look free in development while costing real money at volume.
Cost tracking is the other one. An agent that calls five tools and retries twice on each is a different product from a single completion, and your token bill will tell you long before your tests do.
Where PydanticAI pays off first
Start with one narrow job that has a measurable right answer: classifying inbound support tickets, extracting line items from invoices, deciding which of four routes a request belongs to. Give it a strict result type, write ten eval cases, and run them in CI. If the agent’s output is a typed object built on a schema your team already trusts, the rest of the system never needs to know a language model produced it. That property, more than any benchmark, is why teams keep reaching for this library.