Pydantic AI
Last reviewed
May 25, 2026
Sources
No citations yet
Review status
Needs citations
Revision
v1 ยท 3,192 words
Improve this article
Add missing citations, update stale details, or suggest a clearer explanation.
Suggest edit
CtrlK
Last reviewed
May 25, 2026
Sources
No citations yet
Review status
Needs citations
Revision
v1 ยท 3,192 words
Add missing citations, update stale details, or suggest a clearer explanation.
Pydantic AI is an open-source Python framework for building large language model (LLM) agents, developed by Pydantic Services Inc. and released in beta on December 2, 2024.[1][2] The framework provides a type-safe, model-agnostic abstraction layer on top of provider SDKs from Anthropic, OpenAI, Google, Mistral, Groq, Cohere, and Ollama, with structured outputs validated through Pydantic models.[3][4] Designed by Samuel Colvin and the team behind the pydantic data-validation library, the project applies the same "type hints as schema" approach to agent construction, with explicit primitives for dependency injection, tool registration, streaming, and model context protocol integration.[4][5] Pydantic AI reached its 1.0 stable release on September 4, 2025, after nine months in 0.x development and roughly 15 million PyPI downloads.[6][7]
Pydantic AI grew out of pydantic, the Python data-validation library that Colvin created in 2017 to put runtime semantics on Python's PEP 484 type hints.[8][9] Pydantic v1.0 shipped in October 2019, and by 2023 the library was being downloaded around 22 million times per month from PyPI, with adoption inside openai, anthropic, and Google through their respective Python SDKs.[9][10] Colvin incorporated Pydantic Services Inc. in 2022 and announced a seed round led by sequoia Capital on February 16, 2023, with participation from Partech and Irregular Expression.[11] Crunchbase and trade press later reported the seed amount at $4.7 million.[12][13]
On October 1, 2024, Pydantic announced a $12.5 million Series A led by Sequoia, with Partech and Irregular Expression returning and angels including Logan Kilpatrick and Jason Liu joining the round.[12][14] The same announcement marked the general-availability launch of Pydantic Logfire, the company's observability platform, which had spent five months in open beta.[14] Total disclosed funding stood at $17.2 million as of late 2024.[12]
PydanticAI was first announced publicly on December 2, 2024, when Samuel Colvin published the project's documentation site at ai.pydantic.dev and pushed the initial 0.0.1 series to PyPI.[2][15] The repository was open-sourced under the MIT license on GitHub at pydantic/pydantic-ai.[4] Simon Willison, in a blog post the same day, described the framework as "an Agent Framework / shim to use Pydantic with LLMs" and noted that many existing tools already use Pydantic for defining JSON schemas in function-calling contexts.[15] Coverage in VentureBeat and InfoQ characterized the release as "model-agnostic" and noted that initial provider support included openai, gemini, and groq, with anthropic support planned for a subsequent release.[1][16]
The project iterated rapidly through 2025. On January 15, 2025, Colvin announced v0.0.19, which introduced graph support as the largest new feature since launch, allowing developers to model agent control flow as type-safe directed graphs.[17] After nine months of feedback and approximately 15 million downloads, the team shipped v1.0 on September 4, 2025, with an API stability commitment of at least six months and an additional six months of security fixes following any future v2 release.[6][18] By mid-2025 PydanticAI was, by Pydantic's own measurement, the fastest-growing agent framework by PyPI downloads, with eight million downloads per month.[19] By May 2026 the repository had crossed 17,000 GitHub stars.[4]
The launch documentation framed PydanticAI's design as an attempt to bring "that FastAPI feeling to GenAI app and agent development," extending the type-hints-first philosophy of pydantic from data validation to LLM orchestration.[3][4] The framework is built around four explicit principles.
Type safety throughout. Agents are parameterized generic objects: an Agent[DepsT, OutputT] declares both the type of dependencies passed into tools and the type of structured output the model must return.[20] Tool functions, system-prompt callbacks, and output validators carry full mypy and Pyright support, and Pydantic AI documents that its goal is to "give your IDE or AI coding agent as much context as possible for auto-completion and type checking, moving entire classes of errors from runtime to write-time."[3]
Model-agnostic provider abstraction. A single Agent interface dispatches across provider SDKs. The 1.0 release ships with native support for openai, anthropic, Google (gemini), Groq, mistral ai, cohere, deepseek, xAI's Grok, Perplexity, ollama, Azure AI Foundry, Amazon Bedrock, Google Cloud Vertex, OpenRouter, Together AI, Fireworks AI, cerebras, Hugging Face, GitHub Models, Heroku AI, Vercel AI Gateway, Nebius, OVHcloud, Alibaba Cloud, and SambaNova.[4][21]
No global state, explicit dependency injection. PydanticAI deliberately omits the global registries, "chains" objects, and runnables abstractions common in langchain. Dependencies (database handles, HTTP clients, configuration) are passed to an agent run via a deps argument and surfaced inside tool functions through a RunContext[DepsT] parameter, mirroring the dependency-injection style that made FastAPI testable.[22]
Observable by default. PydanticAI emits OpenTelemetry traces using the GenAI semantic conventions rather than a proprietary trace format, allowing the same traces to be consumed by Pydantic Logfire, Grafana, Datadog, Honeycomb, or any OTel collector.[23][24] Colvin has argued that "the engineering quality is far below that of the rest of the Python ecosystem" in much of the agent-framework space and has cited the team's 100 percent test coverage and unit-tested documentation examples as explicit differentiators.[25][6]
The framework centres on five primitives: the Agent, the Model, the RunContext, tools (registered via decorators or constructor arguments), and the output_type.[20]
An Agent is a generic class parameterized over dependency and output types, typically constructed as Agent[DepsT, OutputT].[20] At construction time the agent is given a model identifier (for example openai:gpt-4o or anthropic:claude-3-5-sonnet-latest), one or more instructions strings or callables, an optional deps_type, and an optional output_type (which can be a Pydantic model, a TypedDict, a primitive type, a union of types, or a callable).[20][26] Three principal entry points exist on an agent: run (async), run_sync (blocking), and run_stream (yields tokens and partial structured output as the model generates).[20]
A Model object wraps a provider SDK. Pydantic AI ships concrete implementations including OpenAIModel, AnthropicModel, GoogleModel, GroqModel, MistralModel, CohereModel, and OllamaModel, plus pass-through implementations for Bedrock, Vertex, OpenRouter, and other gateway providers.[4][21] Each Model normalises the provider's request and response format into a common message-history representation, which means the same agent code can be retargeted across providers by changing the model string.[3]
RunContext[DepsT] is the carrier type for per-run state. Tool functions and validators receive a RunContext as their first parameter, exposing ctx.deps (the typed dependency object), ctx.usage (token and request counters), ctx.model (the active model), and ctx.messages (the conversation history so far).[22] Because the DepsT parameter is propagated by the type system, tool authors get full IDE support for dependency attributes.[22]
Tools are functions the LLM may call. Pydantic AI provides two registration decorators: @agent.tool, for tools that take a RunContext parameter and have access to dependencies, and @agent.tool_plain, for stateless tools.[26] Tool argument schemas are derived automatically from the function's type hints and docstring; Pydantic AI extracts the docstring summary as the tool description and parses parameter descriptions out of Google, NumPy, or Sphinx-style docstring sections.[26] At runtime the LLM's tool-call arguments are validated against the function's signature via Pydantic, and validation failures are returned to the model as a retry prompt rather than raised as Python exceptions.[26]
A Toolset is a collection of related tools that can be attached to multiple agents. ToolDefinition is the lower-level dataclass that describes a single callable to the model, with fields for name, description, parameters_json_schema, and strict.[27] PydanticAI auto-generates ToolDefinition objects from decorated functions, but they can also be constructed manually, which is the mechanism used by integrations with external tool sources such as model context protocol servers.[27]
The output_type parameter on an Agent instructs the framework to coerce the model's final response into a specific structured type.[20] When output_type is a Pydantic model, PydanticAI uses provider-native structured output APIs (JSON mode, response_format, or tool-call mode depending on the provider) and validates the result through Pydantic.[26] If validation fails, the agent automatically resubmits the failure as a system message and asks the model to try again, with the number of retries bounded by an agent-level retries setting.[26] The same machinery supports output_type as a union of Pydantic models, in which case the model is asked to select the correct branch as part of its response.[26]
Agent.run_stream exposes an async context manager yielding a StreamedRunResult. Callers can iterate raw text tokens, partially validated structured output (where Pydantic AI continuously re-parses the in-flight JSON against the target schema), or tool-call events.[3] For models that support delta-encoded tool calls (OpenAI, Anthropic), Pydantic AI reconstructs argument fragments incrementally.[3]
Beginning with v0.0.19 in January 2025, Pydantic AI represents an agent run internally as a directed graph of nodes; each node returns the next node, and the runtime advances the graph until a terminal End node is reached.[17] The graph implementation supports Mermaid diagram export and can be paused and resumed across a Temporal workflow, enabling durable agent execution.[17][6]
The table below summarises the providers that ship in the core pydantic-ai package as of v1.x. Feature columns reflect the framework's documented support for tool calling, streaming, structured outputs, and vision input on at least one model in the provider's catalogue.[4][21]
| Provider | Tool calls | Streaming | Structured outputs | Vision |
|---|---|---|---|---|
| openai | yes | yes | yes (response_format) | yes |
| anthropic | yes | yes | yes (tool-call) | yes |
| Google (gemini) | yes | yes | yes | yes |
| mistral ai | yes | yes | yes | partial |
| Groq | yes | yes | yes | partial |
| cohere | yes | yes | yes | no |
| deepseek | yes | yes | yes | no |
| Grok (xAI) | yes | yes | yes | yes |
| Perplexity | yes | yes | partial | no |
| ollama | yes | yes | yes | partial |
| Azure AI Foundry | yes | yes | yes | yes |
| Amazon Bedrock | yes | yes | yes | yes |
| Google Cloud Vertex | yes | yes | yes | yes |
| OpenRouter | yes | yes | yes | yes |
| Together AI | yes | yes | partial | partial |
| Fireworks AI | yes | yes | yes | partial |
| cerebras | yes | yes | yes | no |
| Hugging Face | yes | yes | partial | partial |
| GitHub Models | yes | yes | yes | yes |
| Heroku AI | yes | yes | partial | no |
| Vercel AI Gateway | yes | yes | yes | yes |
Provider names are accepted as model strings of the form provider:model_name, for example openai:gpt-4o, anthropic:claude-3-5-sonnet-latest, or google-vertex:gemini-1.5-pro.[3][20]
Pydantic AI occupies a distinct niche in the Python agent-framework ecosystem compared to the three best-known incumbents.[28]
langchain, first released by Harrison Chase in late 2022, popularised the "chain" and "runnable" abstractions, the LangChain Expression Language (LCEL), and a large surface area of provider, retriever, and tool integrations.[28] PydanticAI deliberately omits LCEL-style pipe operators and chain objects; control flow is ordinary Python with explicit if and for statements, and tools are plain functions.[4][25] Trade-press analyses position Pydantic AI as preferable when type safety, structured outputs, and Python-native validation matter most, and LangChain as preferable when "fast prototyping, a massive community, and out-of-the-box integrations" are the priority.[28] Pydantic AI does, however, depend on pydantic itself, which is in turn a dependency of LangChain, LlamaIndex, the openai SDK, the anthropic SDK, and Google's ADK, so the libraries are not mutually exclusive at runtime.[4]
llamaindex, developed by Jerry Liu's company and originally branded GPT Index, focuses on retrieval-augmented generation over heterogeneous data sources and offers its own event-driven Workflows abstraction.[28] PydanticAI is not a retrieval framework; it has no first-party document loaders, chunkers, or vector-store adapters, and projects that need those features typically use LlamaIndex (or a vector database directly) alongside PydanticAI tools.[4][28]
dspy, the Stanford-originated framework by Omar Khattab and collaborators, treats prompts as compilable programs and optimises them automatically via teleprompters.[28] PydanticAI does not perform prompt optimisation; instructions are author-written strings or callables and remain unchanged across runs.[20] The two frameworks address adjacent problems: DSPy aims at programmatic prompt design, PydanticAI aims at type-safe agent execution, and a DSPy-compiled program could in principle be wrapped as a PydanticAI tool.[28]
A closer comparison is to the instructor library, another Pydantic-centred library for structured LLM outputs that predates PydanticAI. Instructor patches provider SDKs to return Pydantic models from chat.completions.create calls, while PydanticAI provides the higher-level Agent, tool, and graph machinery; the two are complementary and Instructor's author Jason Liu participated in Pydantic's Series A as an angel investor.[14] Pydantic AI also sits alongside the claude agent sdk and the openai agents sdk as a framework-level rather than provider-specific approach to agent construction.[4]
Pydantic Logfire is the company's observability platform, launched in beta in spring 2024 and reaching general availability on October 1, 2024 alongside the Series A announcement.[14][29] Logfire is built on opentelemetry under the hood, with open-source SDKs for Python, JavaScript/TypeScript, and Rust, and a managed backend that stores traces in a PostgreSQL-compatible store queryable through standard SQL.[29][24] The Python SDK is MIT-licensed and wraps the OpenTelemetry Python package.[24]
For PydanticAI users, Logfire integration is a one-line logfire.configure() call followed by logfire.instrument_pydantic_ai(); thereafter every agent run is captured as an OTel trace with spans for each model call, tool call, and validation step.[24] The Logfire UI provides a conversation-panel view of agent runs, with token counts, model latency, cost estimates, and tool-call argument inspection.[29] Because PydanticAI emits semantic-convention-compliant traces, the same data can be sent to Datadog, Grafana Cloud, Honeycomb, or any OTel collector without Logfire.[23][24]
PydanticAI's repository at github.com/pydantic/pydantic-ai crossed 16,000 stars by early 2026 and reached over 17,000 stars by May 2026.[4][30] Pydantic's own blog reported that PydanticAI was the fastest-growing agent framework by PyPI downloads in 2025, with approximately eight million downloads per month at peak.[19] Cumulative downloads through the v1.0 release on September 4, 2025 reached approximately 15 million.[6]
The framework has been the subject of conference talks by Colvin, including an "Agent Hour" appearance at the MLOps Community on December 19, 2024 titled "Why we built PydanticAI, and why you might care," and an extended interview on the Latent Space podcast covering the graph-based runtime.[31][25] Colvin has also discussed PydanticAI on Software Engineering Daily and the AI Engineering Podcast.[32][33]
The underlying pydantic library, which acts as PydanticAI's validation layer, was reported by Pydantic in February 2026 to have crossed 10 billion total PyPI downloads, with monthly downloads exceeding 550 million.[19] Pydantic itself is a transitive dependency of the openai Python SDK, the anthropic SDK, Google's GenAI SDK, langchain, llamaindex, instructor library, CrewAI, and Hugging Face Transformers, which gives PydanticAI an unusually deep integration surface with the rest of the Python LLM ecosystem.[4]
Pydantic Services Inc. was incorporated in 2022 to commercialise Colvin's open-source work; the company emerged from stealth on February 16, 2023, when Colvin announced a seed round led by sequoia Capital with participation from Partech, Irregular Expression, and angels including Bryan Helmig of Zapier, Tristan Handy of dbt Labs, and David Cramer of Sentry.[11] Crunchbase and Nordic9 later reported the seed at $4.7 million.[12][13]
On October 1, 2024, the company announced a $12.5 million Series A also led by Sequoia, bringing total disclosed funding to $17.2 million.[12][14] TechCrunch reported that the Series A capital was earmarked "primarily for salaries" and for expanding the team beyond 13 employees, "mostly developers."[12] Colvin described the strategic intent as transforming Pydantic from "an open source project to a full stack AI engineer platform" combining the validation library, Logfire observability, and PydanticAI agent framework.[32][14] PydanticAI was developed and released within that Series A funding window, with the December 2024 launch occurring two months after the Series A close.[2][14]