Treating AI as Engineering: How Pydantic AI Broke Through in 2026

When the Pydantic team launched Pydantic AI, they brought proven software engineering practices—type validation, retries, and unit testing—straight into Agent development.

As the Pydantic team emphasized in their launch announcement:

building GenAI applications is still just engineering

Building generative AI applications is ultimately regular software engineering. When you treat non-deterministic language models as remote APIs that can fail at any time, the engineering focus naturally shifts back to rigorous type validation, reliable retries, and unit tests.

Within two years, Pydantic AI accumulated over 20,000 GitHub stars and reached millions of monthly downloads. As an agent framework built directly on Pydantic, what engineering advantages does it offer, and what costs must you weigh before adopting it?


Core Positioning: Integrating AI Applications with Pydantic Models

Pydantic AI uses Pydantic models to validate data, introducing type contracts directly into AI applications.

The team made their motivation explicit in the launch announcement:

We built Pydantic AI because no existing agent framework met our bar for developer ergonomics, engineering quality, and production readiness.

This motivation also crystallized Pydantic AI’s architectural stance: willing to discard over-engineered agent abstractions to safeguard code maintainability.

The framework’s greatest strength lies in its ecological niche: whether it is the OpenAI SDK, Anthropic SDK, Google GenAI SDK, LangChain, or FastAPI, Pydantic has long been universally adopted as the underlying data validation layer.

While other frameworks often introduce custom Message or Document abstractions—forcing developers to write repetitive transformation layers between web request models, framework wrappers, and domain data—Pydantic AI naturally occupies the shortest integration path in Python. From FastAPI inputs and tool arguments to structured outputs, everything flows through native Pydantic models and standard dataclasses, forming an end-to-end type contract.


Two Key Differentiators: Runtime Type Contracts and Zero-API Unit Testing

What sets Pydantic AI apart is extending static type hints into enforceable runtime contracts. This manifests in two primary mechanisms:

1. Self-Correction for Structured Outputs

In Pydantic AI, an agent’s output is bound directly to a Pydantic model. Raw model responses must pass validation before delivery; if field types mismatch or required keys are missing, the framework automatically feeds the validation error back into the conversation, prompting the LLM to self-correct.

from pydantic import BaseModel
from pydantic_ai import Agent

class SupportTicket(BaseModel):
    category: str
    urgency: int  # 1–5

agent = Agent(model="openai:gpt-5", output_type=SupportTicket)
result = agent.run_sync("Customer says the entire system is down and needs immediate resolution")
print(result.output.urgency)  # Guaranteed to be a validated integer

Beyond output validation, tool arguments dynamically generate JSON Schemas from type hints and are validated on every invocation. External dependencies (such as database connections or API keys) are explicitly injected via deps_type using dataclasses. This eliminates implicit global variables and environmental coupling, making external dependencies transparent and dramatically simplifying mocking and isolation during testing.

After using dynamic chain frameworks for two years, AI data analytics engine MindsDB decided to migrate its core pipeline to Pydantic AI. CEO Jorge Torres pointed to their core pain point:

The more freedom we gave the LLM in a loop, the more mistakes it made.

They abandoned autonomous agentic loops where the model dynamically decides its execution path, opting instead for a code-first workflow. They rely on Pydantic AI only for localized, deterministic data contracts and retries at individual steps.

Each step produces a validated Pydantic object, allowing downstream routing logic to operate on verified, deterministic contracts while shedding gigabytes of bloated dependencies.

In the 90-day Nextbuild field test cited by Speakeasy, this runtime type system caught 23 data contract bugs before reaching production—defects that otherwise would have slipped straight into production without strict validation.

2. Testability as a First-Class Citizen

While most agent frameworks rely heavily on live API calls or costly cloud tracing platforms for testing, Pydantic AI ships with built-in TestModel and FunctionModel implementations.

The official documentation defines TestModel as having “no ML or AI, just plain procedural Python code designed to generate data that conforms to tool JSON schemas.”

Combined with the global toggle ALLOW_MODEL_REQUESTS = False, engineers can block network calls to external LLMs inside CI/CD pipelines, using Agent.override(model=...) and capture_run_messages() to assert against internal agent reasoning and tool-calling flows.

This allows agent logic to run fast regression tests in pytest just like ordinary business logic, freeing teams from relying on external tracing platforms or burning through expensive tokens.

In the 90-day Nextbuild field test cited by Speakeasy, Pydantic AI earned a developer experience (DX) score of 8/10, ranking the highest among the five frameworks tested.


Architectural Tradeoffs: State Philosophies of Pydantic AI vs. LangGraph

Entering 2026, the agent framework landscape has moved past its wild-west era. The Speakeasy evaluation observed that, compared to earlier monolithic abstractions, modern frameworks are sharper tools for the job. When evaluating architecture, Pydantic AI and LangGraph represent fundamentally different tradeoffs:

Architectural DimensionPydantic AILangGraph
Core PhilosophySoftware engineering first, strict type enforcementGraph computation first, flexible stateful workflow orchestration
State ManagementStateless by default; long-running processes offloaded to external durable enginesNative checkpointing with automatic step-level persistence
Fault Tolerance & RecoveryRelies on external workflow engines (Temporal, Restate, etc.)Built-in interrupt/resume and human-in-the-loop workflows
Dependencies & Architectural OverheadLightweight; coupled only with Pydantic, no extra abstraction bloatHeavier; deeply bound to the LangChain conceptual ecosystem
Best Suited ForSingle-responsibility microservice agents, precise tool callingLong-running state graphs with complex branching and dynamic loops

The Core State Divergence: Native Checkpointing vs. External Durable Engines

The defining architectural divergence between the two lies in state management.

LangGraph’s strength is its native checkpointing mechanism. It automatically persists complete state to a storage layer at every step; if a server crashes or human review is required, execution resumes seamlessly from the interrupted node.

In contrast, Pydantic AI is stateless by default. Its lifecycle is strictly bounded to a single run: to maintain multi-turn conversations, the application layer passes the history itself—for example, extracting it with result.all_messages() and feeding it back on the next run. The official docs also provide opt-in persistence options such as ConversationStore and conversation=, but none of these are on by default.

When handling long-running, durable execution scenarios—such as multi-day human reviews, asynchronous interrupts, or crash recovery—Pydantic AI does not provide a persistent state machine out of the box. Instead, it delegates through clean interfaces to mature external distributed workflow engines like Temporal, DBOS, Prefect, and Restate.

If your system requires complex conditional branching and long-lived interruption waiting, LangGraph’s native checkpointing is better equipped to manage state across prolonged lifecycles. But if your agents have clear, focused boundaries and do not need to manage persistent state internally, Pydantic AI avoids forcing a heavy workflow runtime into your stack.

TIP

A complementary “outer state graph, inner type contract” architecture: Pragmatic compromises have already emerged in production: LangGraph orchestrates cross-node state graphs and human review, while individual execution nodes are encapsulated inside Pydantic AI—letting state graphs handle long-running workflows while type contracts govern node-level execution. This division cleanly aligns with the respective strengths of both tools.


Costs You Cannot Ignore: Version Fatigue, Ecosystem Gaps, and Governance Deficits

Despite its celebrated engineering quality, adopting Pydantic AI comes with concrete costs that cannot be overlooked:


Evolution and Outlook: A Lean Core and Deterministic Engineering Stance

To keep its core stable amid rapid iteration while aggressively expanding capabilities against fierce competition, Pydantic AI established a clear architectural separation in v2:

Core stays small and stable… Everything else lives in the Harness, where it can move fast.

The team outlined a distinct division between the core and perimeter:

Architectural LayerResponsibilities & Core CapabilitiesIteration Cadence & Compatibility Guarantees
CoreLow-level infrastructure: type safety, model integration, dependency injectionKept lean, highly compatible, and long-term stable
HarnessHigh-level capabilities: memory management, guardrails, subagents, file accessPackaged via capability specs, allowing rapid experimentation

Whether breaking changes will truly subside still hinges on how rigorously the team honors that three-month compatibility window between v2 and v3.