Most AI agent tutorials start with the language model and end with a pile of string parsing, ad-hoc tool arguments and fragile JSON checks. That approach works for a demo. It gets painful the moment an agent becomes a real application. Pydantic AI takes a different path: use Python types and Pydantic models as the contract around the agent, so model outputs, tool inputs and dependencies can be validated instead of treated as untrusted strings.
The framework is now on its second major generation. Pydantic AI v2 became stable on June 23, 2026 after the project reached v1 in September 2025 and spent more than 100 releases refining the API. V2's biggest architectural shift is a capability and harness-oriented design, where tools, instructions, hooks and model settings can be composed around an agent.
This guide explains the framework from the perspective that actually matters to builders: how to create an agent with typed output, how to expose typed tools, how to pass application dependencies, how to validate and retry model output, how to test the system, and where Pydantic AI fits compared with larger agent orchestration frameworks.
QUICK ANSWER
Pydantic AI is a Python agent framework from the Pydantic team. Its main value is not simply that it can call an LLM. The value is that it makes the boundaries around an agent explicit and typed. You can define the result you expect, define tool arguments with normal Python types, inject application dependencies, validate model output, and test the agent with deterministic model substitutes.
For a small or medium Python agent, Pydantic AI is an excellent choice when reliability and developer ergonomics matter more than having a large orchestration graph built into the framework. For complex multi-agent workflows with branching, persistence and explicit state machines, a graph framework such as LangGraph can be a better outer orchestration layer. The two are not mutually exclusive.
The current starting point is Pydantic AI v2. A basic project can be installed with uv add pydantic-ai, and the project maintains a version policy intended to avoid breaking changes in minor releases.
1. What Is Pydantic AI?
Pydantic AI is an agent framework for Python built by the same organization behind Pydantic, the validation library widely used in Python applications. The central idea is straightforward: an AI agent should have machine-checkable interfaces rather than vague text contracts.
A normal agent has at least four boundaries that benefit from types. The model should return a known result shape. Tools should receive valid arguments. The application should provide dependencies such as database clients, authenticated user information or service configuration. And the framework should turn failed outputs into a controlled retry or error path instead of quietly accepting malformed data.
2. Why Type Safety Matters for AI Agents
LLMs are probabilistic. Your application code is not. That mismatch is the core engineering problem. A model might understand that a customer lookup needs an ID, but it can still return a missing field, the wrong type or a value outside the business rules.
Type safety does not make the model deterministic. It moves uncertainty to an explicit boundary where your application can inspect it. If the model returns a date, you can require a date. If a tool expects an integer customer ID, the generated arguments must conform to that contract. If the final agent response must contain a risk score between 0 and 1, your result model can enforce it.
This is especially important once agents start taking actions. A bad paragraph of text is annoying. A malformed tool call that creates an invoice, updates a database or sends an email can be an operational incident. Strong schemas do not eliminate that risk, but they reduce an entire class of avoidable failures.
3. Install Pydantic AI v2
The official Pydantic AI upgrade guide lists v2.0.0 as the stable release from June 23, 2026 and gives uv add pydantic-ai as the installation command.
uv add pydantic-ai
You can also use pip, but for a modern Python project, uv keeps the environment and dependency workflow simple. Start with a fresh virtual environment and pin production dependencies through your normal project lockfile process.
One important version note: Pydantic AI v2 intentionally contains breaking changes that could not be introduced under the v1 stability promise. The official migration guidance recommends upgrading through the latest v1 release and clearing deprecation warnings before moving to v2.
4. Your First Type-Safe Agent
The smallest useful example is an agent that returns structured data rather than free-form prose. Imagine a support classifier that must return a category, urgency and a short explanation.
from pydantic import BaseModel
from pydantic_ai import Agent
class TicketResult(BaseModel):
category: str
urgency: int
summary: str
agent = Agent(
"openai:gpt-5.6-mini",
output_type=TicketResult,
)
result = agent.run_sync(
"Customer was charged twice and wants a refund."
)
print(result.output.category)
print(result.output.urgency)
print(result.output.summary)The important part is output_type=TicketResult. You are not asking the model to return some JSON that you hope to parse later. You are declaring the application's expected result contract. Pydantic handles validation of the returned structure before your code treats it as a valid application object.
In a production system, the model name would be chosen from the provider or deployment configuration you use. Pydantic AI supports a broad provider ecosystem, so the application can keep its agent interface while the underlying model changes.
5. Validation: Turn AI Uncertainty Into a Controlled Failure
Suppose urgency must be an integer from 1 to 5 and the category must come from a fixed set. Put those rules into the type instead of writing validation after the model call.
from typing import Literal
from pydantic import BaseModel, Field
class TicketResult(BaseModel):
category: Literal["billing", "technical", "account", "other"]
urgency: int = Field(ge=1, le=5)
summary: strNow the model cannot satisfy the application contract by returning urgent as a string when an integer is required, or by inventing a sixth category. Validation creates a hard boundary between probabilistic generation and deterministic business logic.
This is where Pydantic AI becomes more than a convenient agent wrapper. Pydantic's validation system is the language of the application's contract. The agent's job is to produce an object that satisfies that contract.
6. Typed Tools Are the Second Half of the Pattern
Structured output handles the model-to-application boundary. Tools handle the model-to-world boundary. A tool should be treated as an API with a schema, not as a Python function the model can invoke with arbitrary text.
from pydantic_ai import Agent, RunContext
agent = Agent("openai:gpt-5.6-mini")
@agent.tool
def get_customer_status(ctx: RunContext[None], customer_id: int) -> str:
"""Return the current status for a customer."""
return f"Customer {customer_id} is active"
result = agent.run_sync(
"Check customer 4812 and tell me their status."
)The function signature gives the tool a contract. The model needs to generate a valid integer for customer_id. Your function can then operate on a typed value instead of parsing a string that happened to look like an ID.
For production actions, add another layer. The tool's schema validates shape, but authorization, business rules and side effects still belong in your application. An integer customer ID does not mean the current user is allowed to access that customer. Type safety is not access control.
7. Dependencies: Pass Real Application State Safely
Real agents need access to application services. They might need a database session, an authenticated user, a feature flag service or an internal API client. Passing those objects through globals makes tests and concurrent execution harder. Pydantic AI supports dependency injection through a typed dependencies object.
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
@dataclass
class Deps:
user_id: str
account_service: object
agent = Agent("openai:gpt-5.6-mini", deps_type=Deps)
@agent.tool
def get_balance(ctx: RunContext[Deps]) -> str:
return ctx.deps.account_service.get_balance(ctx.deps.user_id)The key idea is separation. The agent defines what dependencies it expects, while the caller supplies the concrete objects for each run. That makes the same agent easier to test with fake services and easier to reuse in different application environments.
Dependencies are also where application-specific safety belongs. Instead of giving a model raw access to your whole database, expose a small typed service interface that enforces permissions and limits the data the agent can request.
8. Dynamic Instructions and Context
Agents often need instructions that depend on the current user or task. Pydantic AI supports dynamic context so the prompt can be constructed from dependencies rather than hardcoded into one static system message.
For example, an enterprise support agent might load the user's language, account tier and enabled products from a dependency service. The agent can then receive a targeted instruction set for that run. This is a better design than injecting a giant global prompt containing information irrelevant to most users.
That approach fits directly with the principles in our What Is Context Engineering? Complete Guide (2026), where the focus is on deciding what information reaches the model and when.
9. Retries and Validation Errors
A production agent should assume that model output sometimes fails validation. The right response is not to manually parse the result until something works. The framework can use the validation feedback as part of a controlled retry strategy.
That creates a useful loop: generate, validate, report the contract violation, retry within a defined limit, then fail explicitly if the model still cannot satisfy the schema. The important operational controls are the maximum number of retries, timeout budget, token budget and logging.
Do not create unlimited self-correction loops. A model repeatedly failing the same schema can turn a small request into an expensive and slow request. A production agent needs a clear terminal failure path.
10. Testing AI Agents With Pydantic AI
Testing is one of the strongest reasons to choose a typed agent framework. You want unit tests that exercise your application logic without spending money on a real model for every test. Pydantic AI provides testing and evaluation utilities, including ways to substitute or override model behavior so tests can focus on tool wiring, dependencies and output contracts.
A sensible test matrix has three levels. First, schema tests verify that valid and invalid outputs behave correctly. Second, tool tests verify authorization and side effects without any LLM. Third, agent tests use a controlled model path to check that the agent selects the expected tools and produces the expected result shape.
Then add a small evaluation suite for real model behavior. This is where you test the probabilistic part of the system: representative prompts, edge cases, ambiguous user requests and tool failure recovery.
11. Observability and Production Debugging
An agent that works in a notebook can still be a nightmare in production. You need to know which model ran, what tools were called, how many retries occurred, how long each step took and where validation failed.
Pydantic AI sits naturally inside a broader observability stack. Capture structured events around agent runs, tool execution, validation failures and final outcomes. Keep sensitive prompt and response data governed by the same privacy controls you apply to the rest of your application.
This becomes more important as agents become long-running systems. A single failed tool call can trigger a retry, which can change the next model decision, which can create another tool call. Without trace data, debugging becomes guesswork.
12. Model Providers: Avoid Locking the Agent Contract to One Vendor
One practical strength of Pydantic AI is that the agent interface is separated from the provider choice. The provider string or model object identifies the backend, while your result types, tools and dependency contracts remain application code.
That makes experimentation easier. You can compare a closed frontier model with an open-weight model without rewriting every tool and result parser. The benchmark should be your application workload, not a generic leaderboard.
Our Best Open Source AI Models August 2026: Full Collection tracks the current open-model field, while our Qwen3.8-Flash-Next review covers one current option in depth.
13. Pydantic AI vs LangGraph
These frameworks are often compared as though you must choose one. That is too simplistic. Pydantic AI is strongest around the typed agent itself: instructions, model interaction, structured output, tools and dependencies. LangGraph is strongest when you need explicit graph control, persistent state, branching workflows and complex multi-agent orchestration.
For support agent, extraction agent or tool-using assistant, start with Pydantic AI. For a workflow with planner, researcher, reviewer and executor nodes that can pause, resume and branch, use LangGraph or another orchestration layer. You can also use Pydantic AI for the typed agent nodes inside a larger graph.
See our How to Use LangGraph for Multi-Agent Systems (2026) for the graph-oriented side.
14. Pydantic AI vs Building Your Own Agent Loop
You can always write your own loop: send prompt, inspect tool call, execute function, append result, call model again. The first version can fit in a few dozen lines. That is not the problem. The problem is what happens after six months of feature requests.
Retries, structured output, model-specific response formats, streaming, dependency injection, testing, provider changes and tracing all create edge cases. A framework earns its keep by making those boundaries explicit and reusable.
Building your own loop still makes sense for a very small system or when you need extremely custom behavior. But once you need typed contracts and several production integrations, the cost of maintaining your own agent protocol can exceed the cost of adopting a framework.
15. Build a Production-Ready Pattern
The critical design rule is that the model should not be the security boundary. Tool schemas and Pydantic validation can make inputs safer, but authorization must live in deterministic application code. A type-safe delete_user(user_id: int) function is still dangerous if it does not check whether the current actor is allowed to delete that user.
For agent permission design, see our How to Secure AI Coding Agents in 2026.
16. Pydantic AI v2: What Changed?
Pydantic AI v2, released June 23, 2026, is not a cosmetic update. The project moved toward a harness-first design in which a capability becomes a composable unit containing tools, hooks, instructions and model settings. The agent framework remains intentionally small, while additional capabilities can live in the first-party Pydantic AI Harness, third-party packages or your own code.
The practical lesson is that the framework is becoming less about one monolithic Agent class doing everything and more about composable capabilities around an agent run. That is a good direction for production systems because agent complexity tends to grow around the inner model call, not inside it.
The upgrade path matters too. Pydantic AI's version policy says minor releases will not intentionally introduce breaking changes, and v1 receives security fixes for at least six months after v2's stable release. Teams moving from v1 should follow the official upgrade guide rather than blindly changing imports and hoping the tests catch everything.
17. Common Mistakes With Pydantic AI
- Treating a Pydantic schema as a replacement for authorization. It is not.
- Giving an agent too many tools. More tools create more opportunities for wrong tool selection.
- Using an enormous output model when a small typed object would do.
- Allowing unlimited retries when validation fails.
- Passing raw database clients or privileged services without limiting what the tool can access.
- Skipping evaluation because the agent passes a few happy-path unit tests.
- Using a one-million-token context as a substitute for retrieval and context management.
- Assuming the strongest model is always the cheapest production model.
18. A Practical Project Structure
app/
agents/
support.py
research.py
models/
outputs.py
domain.py
tools/
customer.py
search.py
billing.py
services/
accounts.py
retrieval.py
tests/
test_agents.py
test_tools.py
settings.py
main.pyKeep the agent definitions thin. Put deterministic business rules in services and domain models. Put tool adapters in their own modules. This prevents the agent file from becoming a giant mixture of prompt instructions, database code and business logic.
19. When Should You Choose Pydantic AI?
20. Final Verdict
Pydantic AI is one of the better choices for Python developers who want agent code to look like normal application code instead of a collection of prompt strings and JSON dictionaries. Its defining advantage is the typed boundary around the model: structured results, typed tool arguments, explicit dependencies and validation are all first-class engineering concerns.
The timing is also good because Pydantic AI v2 is now stable. The June 23 release moved the project toward a more composable capability model while keeping the core framework deliberately small. The official version policy also gives teams a clearer upgrade path than many fast-moving agent libraries provide.
But do not oversell what types can do. Pydantic AI cannot make an LLM reliable by itself. It cannot authorize users, prevent prompt injection, make a bad tool safe or guarantee that a reasoning chain is correct. What it does is narrow the failure surface and make many failures visible to deterministic code.
My recommendation is simple: use Pydantic AI when your main problem is building a reliable Python agent, use a graph framework when your main problem is orchestrating a complex workflow, and combine them when you need both. For teams building production agents in 2026, typed contracts are not a luxury. They are one of the easiest ways to turn an LLM demo into software that can survive contact with the real world.
Frequently Asked Questions
What is Pydantic AI?
Pydantic AI is a Python framework for building AI agents with typed model outputs, typed tool arguments, dependency injection and validation. It is maintained by the Pydantic team.
What is Pydantic AI v2?
Pydantic AI v2 is the stable second major release, published June 23, 2026. It introduces a more composable capability and harness-oriented architecture while keeping the core framework small.
Why is Pydantic AI type-safe?
It lets you describe model results and tool inputs with Python and Pydantic types, then validate generated data against those contracts before application code uses it.
Can Pydantic AI return structured output?
Yes. You can define a Python type or Pydantic model as the expected output and have the agent return a validated object rather than raw text.
Can Pydantic AI call tools?
Yes. Tools are normal Python functions with typed arguments, which lets the agent invoke application capabilities through a defined interface.
How does Pydantic AI handle dependencies?
You can declare a dependency type for the agent and access the supplied runtime dependency object inside tools and dynamic instructions through the run context.
Does Pydantic AI work with different model providers?
Yes. The framework is designed to work across multiple providers, so the agent's typed interfaces can remain stable while the underlying model changes.
Is Pydantic AI better than LangGraph?
Neither is universally better. Pydantic AI is stronger for typed agent contracts and Python agent code. LangGraph is stronger for explicit graph orchestration, branching and persistent workflow state.
Can Pydantic AI prevent prompt injection?
No. Types and validation reduce malformed-data risk, but prompt injection remains an application security problem that requires tool restrictions, authorization, sandboxing and careful context handling.
Is Pydantic AI good for production?
Yes, when combined with proper testing, authorization, observability, bounded retries and least-privilege tools. The framework improves engineering reliability but does not remove the need for normal application security.
Recommended Blogs
- How to Use LangGraph for Multi-Agent Systems (2026)
- What Is Context Engineering? Complete Guide (2026)
- Model Routing for AI Coding Agents: How to Cut Costs Without Losing Quality
- How to Secure AI Coding Agents in 2026: Permissions, Sandboxing, MCP & Secrets
- Best Open Source AI Models August 2026: Full Collection
- Qwen3.8-Flash-Next Review: Benchmarks, Cost & Is It Worth It? (2026)
Resources & Community
Join our community of 70,000+ AI enthusiasts and learn to build powerful AI applications. Whether you're a beginner or an experienced developer, Build Fast with AI helps you understand and implement AI in your projects.
- Website - buildfastwithai.com
- LinkedIn - Build Fast with AI
- Instagram - @buildfastwithai
- Founder Twitter - @satvikps
- Twitter - @BuildFastWithAI
Agentic AI Launchpad 2026
A structured 6-week cohort program that takes you from AI basics to building and deploying real-world agentic AI systems. Includes live sessions, expert mentorship, project reviews and a builder community network.
Ready to go from learning to building? Join the next cohort: Agentic AI Launchpad 2026
Free AI Resources
Access free tools, workshops and micro-learning to keep building.
