# Pydantic AI Pydantic AI is a Python agent framework built by the [[Pydantic]] team. The headline pitch: bring the FastAPI-style "type hints + automatic validation" developer experience to AI agents. If you already write Python with Pydantic models, the framework feels native ; agents, tools, dependencies, and outputs are all typed end-to-end and validated at runtime via the same `pydantic-core` engine. It sits at the *agent-runtime / framework* layer of [[AI SDKs]], peer to [[OpenAI Agents SDK]], [[Microsoft Agent Framework]], and [[Mastra AI]]. ## Core Primitives - **Agent** ; a configured model + system prompt + tools + dependencies. Generic over the dependency type and the output type, both at the type level - **Tool** ; a Python function decorated to be agent-callable; the tool's arg list defines a [[Pydantic]] schema automatically - **Dependencies (`deps_type`)** ; a typed object passed to every tool/system-prompt callable; lets you inject DB connections, API clients, user context cleanly - **Result type** ; the agent returns a typed instance (a Pydantic model), validated server-side and client-side - **Streaming** ; for both text and structured outputs - **Multi-agent / handoffs** ; agents can call other agents as tools ## Example ```python from pydantic import BaseModel from pydantic_ai import Agent, RunContext class WeatherDeps: api_key: str class WeatherReport(BaseModel): city: str temp_c: float summary: str agent = Agent[WeatherDeps, WeatherReport]( model="anthropic:claude-sonnet-4-6", deps_type=WeatherDeps, output_type=WeatherReport, system_prompt="You answer weather questions concisely.", ) @agent.tool async def get_temp(ctx: RunContext[WeatherDeps], city: str) -> float: return await fetch_temp(ctx.deps.api_key, city) result = await agent.run("What's the weather in Lisbon?", deps=WeatherDeps(api_key="...")) print(result.data) # WeatherReport(city='Lisbon', temp_c=21.4, summary='...') ``` The whole thing typechecks: `result.data` is a `WeatherReport`, mypy/pyright know it, the LLM is forced to produce JSON matching it, and validation happens at the boundary. ## Why It's Different Most Python agent frameworks treat the *prompt* as the contract. Pydantic AI treats the *types* as the contract: - **Tool schemas come from function signatures** ; no separate JSON-schema file, no decorator with redundant metadata - **Dependencies are injected, not held** ; like FastAPI's `Depends`, this keeps tools pure-ish and testable - **Output validation is enforced**: if the model returns malformed JSON, the framework retries with the validator's error message in the prompt automatically - **End-to-end typing means refactoring an agent's API is a normal IDE refactor**, not a search-and-pray exercise ## Provider Support Provider-neutral via a small adapter layer: - [[Anthropic SDK|Anthropic]] - [[OpenAI SDK|OpenAI]] - [[Google Gen AI SDK|Google Gemini]] - [[Mistral SDK|Mistral]] - [[Groq]] - Cohere, [[Vercel AI Gateway]], local Ollama, and a long tail of OpenAI-API-compatible endpoints Unlike OpenAI Agents SDK, Pydantic AI does not nail itself to one vendor. ## When To Use It - **Python-first agent app where typed I/O matters** ; ETL on LLM outputs, structured extraction, tool-heavy workflows where contracts must hold - **Production-grade agents needing testability** ; the dependency injection model makes mocking trivial - **Multi-agent flows where each agent has a distinct typed output** ; the typing actually pays for itself ## When Not To Use It - **TypeScript-only project** ; use [[Vercel AI SDK]], [[Mastra AI]], or the TS [[OpenAI Agents SDK]] instead - **Trivial single-prompt apps** ; the type machinery is overkill; just use the [[OpenAI SDK]] or [[Anthropic SDK]] directly - **You don't want Pydantic in your stack** ; rare in modern Python AI work, but possible ## Comparison - **vs [[OpenAI Agents SDK]]**: similar layer; OpenAI Agents SDK leans into multi-agent handoffs as the killer feature; Pydantic AI leans into typed I/O. They overlap, but the *bias* is different - **vs [[Microsoft Agent Framework]]**: MAF is broader (multi-language, .NET-first, enterprise telemetry); Pydantic AI is narrower (Python, typed-I/O-first, FastAPI-shaped DX) - **vs raw [[Anthropic SDK]] / [[OpenAI SDK]]**: those are model SDKs; Pydantic AI is the agent loop with retries, tool dispatch, and structured outputs on top - **vs LangChain / LlamaIndex**: Pydantic AI is opinionated-but-small; the LangChain ecosystem is larger but historically suffered from API churn and abstraction sprawl ## License MIT. ## References - Documentation: https://ai.pydantic.dev/ - GitHub: https://github.com/pydantic/pydantic-ai ## Related - [[Pydantic]] - [[Python]] - [[AI SDKs]] - [[OpenAI Agents SDK]] - [[Microsoft Agent Framework]] - [[Mastra AI]] - [[Anthropic SDK]] - [[OpenAI SDK]] - [[Google Gen AI SDK]] - [[Mistral SDK]] - [[AI Agent Harness]]