PydanticAI

PydanticAI is a Python agent framework built by the team behind Pydantic, led by Samuel Colvin, the engineer who created the Pydantic validation library used throughout the Python ecosystem. Released on December 2, 2024, during AWS re:Invent week, it reached version 1.0 stable on September 4, 2025, after 15 million downloads. The framework is MIT-licensed and free to use. Its core promise: bring the same developer experience that made FastAPI the default Python web framework to building AI agents, replacing ad-hoc JSON parsing and brittle prompt engineering with proper type contracts and validated outputs.

PydanticAI supports OpenAI, Anthropic, Google, xAI, Amazon Bedrock, Groq, Mistral, Ollama, Cohere, OpenRouter, Hugging Face, and Cerebras out of the box. Key features include structured output validation via Pydantic models, a dependency injection system using RunContext that passes database connections and API clients cleanly into tools, streaming with real-time validation, Model Context Protocol (MCP) support, human-in-the-loop tool approval, multi-agent architectures, and durable execution with Temporal integration. Tight integration with Pydantic Logfire provides OpenTelemetry-based observability for tracing agent runs, tracking token costs, and debugging tool calls in production. By May 2026 the repository has over 16,800 GitHub stars, 241+ releases, and is used in production by teams building on Amazon Bedrock AgentCore.

What PydanticAI actually does in May 2026

PydanticAI centers on a single Agent class that wraps an LLM, a set of tools, a system prompt, and a structured output schema. When the agent runs, it validates the model's output against a Pydantic model on every call, automatically retrying with corrective feedback if validation fails. This removes the single largest category of production failures in agent systems: the LLM returning malformed, missing, or wrong-typed data that crashes downstream code.

The dependency injection system is the second major differentiator. Instead of passing configuration through global state or environment variables, tools receive a typed RunContext[Dependencies] object at runtime. In practice this means a database connection, an external API client, or user context can be injected cleanly at agent invocation time, making tools unit-testable without live LLM calls. This is a design pattern borrowed from FastAPI's dependency system and it solves a genuine pain point teams hit when scaling agent codebases beyond a single file. Writing a test for an agent tool no longer requires a live LLM call or a live database: you pass a mock dependency object into RunContext and assert against the result.

Streaming support includes real-time validation of structured partial outputs, not just token streaming. This matters for dashboards and live UIs that render incremental structured data rather than raw text: the framework validates each partial output chunk as it arrives, so the application never has to handle a validation error after the stream completes. Graph-based workflows, added via PydanticAI's Graph API, allow modelling complex agentic flows as typed state machines with IDE-verified transitions between states. Multi-agent communication (agent-to-agent handoffs), MCP server/client support, and durable execution (agents that can pause, persist state, and resume after interruption via Temporal) round out the feature set. The roadmap as of early 2026 includes prompt caching, embeddings support, context-free grammar output, and expanded MCP resource support.

One concrete example of how this plays out in practice: a legal document classification system built on PydanticAI reported 94% accuracy compared to 67% with keyword matching. An e-commerce customer support agent auto-resolved 38% of incoming tickets with 96% satisfaction scores. A real-estate CRM integration processed 40-60 concurrent notifications in under 8 seconds. These are not PydanticAI marketing claims; they are numbers published by individual developers who switched to the framework specifically to escape validation failures in previous tooling.

"The fourth time I had to debug a LangChain agent that silently returned malformed JSON and crashed a client's order processing pipeline, I decided I was done patching type errors at midnight." - jahanzaibai, DEV Community, 2025

Where PydanticAI sits versus LangChain and smolagents

PydanticAI vs. LangChain: LangChain has 96k+ GitHub stars, a mature integration library, and years of production deployments behind it. It is not going away. But the framework carries significant accumulated complexity: a ~300MB footprint, multiple deprecated patterns (legacy AgentExecutor vs. newer LangGraph), and an architecture that separates ChatModel, prompt templates, AgentExecutor, and RunnableWithMessageHistory into distinct layers that must be wired together. For structured output, LangChain cannot combine with_structured_output() and additional tools in the same agent without a custom StructuredResponseTool workaround. PydanticAI handles this natively. For dependency injection, LangChain requires subclassing BaseTool with a class-based tool; PydanticAI uses plain functions with RunContext. The tradeoff is ecosystem breadth: LangChain has connectors PydanticAI simply does not have yet.

PydanticAI vs. smolagents: HuggingFace's smolagents takes the opposite architectural bet. Its entire core is roughly 1,000 lines of Python. Agents write and execute Python code directly (code agents) rather than calling predefined tools via JSON schemas. This produces efficiency gains: smolagents claims approximately 30% fewer LLM calls on complex benchmarks compared to JSON-style tool usage. The cost is that smolagents has no built-in structured output validation, no native async support, and limited memory handling. PydanticAI enforces data consistency at every boundary; smolagents optimizes for experimentation speed and minimal footprint. If you are prototyping on HuggingFace-hosted models and want something running in an hour, smolagents wins. If you are building a compliance-sensitive production system where every output must validate against a schema, PydanticAI wins.

Worth noting: DSPy occupies a different adjacent space, optimizing prompt programs algorithmically rather than providing a runtime execution layer. LangGraph (part of the LangChain ecosystem) is the most direct competitor for stateful multi-agent orchestration. LiteLLM is complementary: a provider-agnostic routing layer PydanticAI can sit on top of. CrewAI targets role-based multi-agent systems with a higher-level abstraction that trades control for simplicity.

What the agent loop reality looks like

A typical PydanticAI workflow starts with defining a Pydantic model for the expected output, creating an Agent with a system prompt and a model backend, then decorating Python functions as tools. Running the agent returns a typed result object, not a string. The IDE knows the shape of every tool argument and every output field before the code runs.

For observability, calling logfire.configure() and logfire.instrument_pydantic_ai() activates automatic tracing of every LLM call, every tool invocation, and every validation attempt. The OpenTelemetry foundation means traces can be exported to any compatible backend, not just Logfire's commercial platform. This is a meaningful distinction: some teams use Datadog or Grafana already and do not want a second observability vendor.

Production teams report solid results. One developer documented 94% accuracy on legal document classification (up from 67% with keyword matching), 38% auto-resolution of e-commerce support tickets with 96% satisfaction scores, and processing 40-60 concurrent real-estate CRM notifications in under 8 seconds. These numbers come from teams that specifically switched to PydanticAI to stop chasing JSON parsing failures at 2am.

"After spending too much time hunting down attribute access bugs in dynamically typed agent chains, this matters more than any benchmark number." - jahanzaibai, DEV Community, 2025

Who PydanticAI is built for

The clearest signal: if you have used FastAPI and you think of Python's type system as infrastructure rather than documentation, PydanticAI will feel immediately familiar. The framework targets engineers who want to treat agent development as normal software engineering, with unit tests, typed contracts, and IDE support, rather than as prompt-craft paired with hope.

It fits well in teams that already use Pydantic (which at this point is most Python teams working with LLMs, given that the OpenAI SDK, Google ADK, and LangChain itself all depend on Pydantic for validation). Adopting PydanticAI is additive rather than a full rewrite. It also fits compliance-sensitive domains: finance, healthcare, legal, where every AI output must be auditable and structured. Thoughtworks moved it to "Trial" in November 2025, their signal that enterprises should use it on a real project to build understanding of the category.

It is a reasonable choice for teams using Amazon Bedrock AgentCore, where PydanticAI is a first-party supported framework. It integrates naturally alongside LiteLLM for teams routing across multiple providers.

What PydanticAI is not

PydanticAI is not a general-purpose agentic Swiss army knife for every stack. A few honest limits:

It is Python-only. There is no JavaScript, TypeScript, or other language SDK. If your backend is Go, Java, or Node.js, you are looking at a different framework.

Multimodal inputs (image, audio, video) are not supported in the agent core as of mid-2026. The framework processes text and structured data; passing an image into a tool requires manual handling outside the framework's validation layer.

For large-scale multi-agent orchestration with complex state graphs, LangGraph has more mature tooling. PydanticAI's Graph API is functional but newer, and developers report that ergonomics for sprawling multi-agent systems are still a work in progress.

The Logfire dependency concern is worth flagging. The observability integration is excellent and genuinely useful, but the Pydantic team has commercial incentives to steer users toward Logfire's paid tiers. The framework emits OpenTelemetry data, so you are not hard-locked, but teams that already have an observability stack (Datadog, Honeycomb, Grafana) should validate the export path before committing.

There are also known issues worth being aware of: a v1.30.0 release accidentally introduced a hard dependency on openai v2.8.0 that broke existing projects (GitHub issue #3707), retry logic does not always resolve validation failures as expected (issue #739), and DeepSeek model support has had mapping bugs. An active development team with 364 open issues means the framework is responsive but still has rough edges.

Skip PydanticAI if: you want something running in an afternoon with no Pydantic knowledge, your stack is not Python, you need mature multimodal agent tooling, or you need the breadth of LangChain's 300+ integrations.