Pydantic AI

Pydantic AI is a Python framework for building AI agents that validates every LLM response against a defined schema before the result reaches the next step in a prompt chain.

What It Is

When you chain multiple LLM calls together — each step taking the previous step’s output as its input — the weakest link is usually data format. A model that returns "high" instead of {"severity": "high"} breaks the parser two steps downstream. By the time the error surfaces, the stack trace points to the wrong place.

Pydantic AI addresses this by treating LLM output as a typed Python object from the start. You define a Pydantic model that describes the structure you need — class SentimentResult(BaseModel): score: float; label: str — and pass it to the agent as the expected output type. The framework handles the prompt engineering needed to steer the model toward that shape, validates the response, and retries automatically if validation fails. Your code receives a proper Python object, not a string to parse.

Think of it like a typed function signature for an AI call. Just as a function that returns Optional[str] tells callers what to expect, an agent configured with result_type=SentimentResult gives the rest of your pipeline a guarantee it can rely on.

The framework organizes work around three concepts. An Agent wraps a single LLM interaction — it holds the model, the output schema, the system prompt, and any tools the model can call. A RunContext carries dependencies injected at runtime (database connections, API clients, request state) without threading them through every function. Tools are typed Python functions the agent can invoke; their arguments and return values pass through Pydantic validation too, so the entire tool-calling loop is schema-enforced, not just the final response.

Pydantic AI supports the major AI providers — OpenAI, Anthropic, Google Gemini, Groq, Mistral, and others — through a common interface. Switching models means changing one configuration line, not rewriting integration code.

For prompt chaining specifically, Pydantic AI acts as the contract between steps. Each node in a chain defines what data it accepts and what structure it returns. A classification step that guarantees a Category enum feeds reliably into a routing step that branches on that enum’s value. Without that contract, every step must defensively parse whatever the previous step happened to return.

How It’s Used in Practice

The most common scenario: a Python developer building a document processing pipeline where each stage needs the previous stage’s output in a specific shape. Stage one extracts key entities from raw text. Stage two scores the document’s relevance based on those entities. Stage three routes it to a workflow based on the relevance score. Each stage is a Pydantic AI agent; each agent’s result_type is the schema the next stage expects.

A developer working on this kind of pipeline would define the schemas first — EntityList, RelevanceScore, RoutingDecision — and then write agents that produce them. If a model response doesn’t match the schema, the agent retries with the validation error appended to the prompt, giving the model a chance to self-correct before raising an exception.

Beyond chaining, the same pattern appears in structured data extraction (parsing contract clauses into typed objects), classification pipelines (categorizing support tickets into an enum), and tool-augmented agents (where the agent decides which tool to call, calls it, and returns a typed result).

Pro Tip: Define your output schemas before writing any agent prompts. The schema is the spec — once you know exactly what shape you need, the prompt almost writes itself. Start narrow (three fields) and expand as you understand what the model reliably produces.

When to Use / When Not

Common Misconception

Myth: Pydantic AI is just a thin wrapper that forces LLMs to return JSON.

Reality: JSON enforcement is one feature. Pydantic AI is a full agent runtime: it handles retry logic on validation failure, tool calling with schema enforcement, dependency injection, streaming, and multi-provider model switching. The goal is production-grade agent code that behaves predictably, not a JSON prompt helper.

One Sentence to Remember

Pydantic AI lets you treat LLM output as a typed contract — if the model’s response doesn’t match your schema, the agent retries automatically, so format errors never reach the next step in your chain.

FAQ

Q: Does Pydantic AI work with both OpenAI and Anthropic models? A: Yes. It provides a unified interface for OpenAI, Anthropic, Google Gemini, Groq, Mistral, Ollama, and other providers. Switching models requires changing one configuration parameter, not rewriting agent code.

Q: How is Pydantic AI different from using the OpenAI response_format parameter directly? A: response_format asks for JSON but doesn’t validate structure or retry on mismatch. Pydantic AI validates against a full schema, retries with the validation error as feedback, and works across providers — not just OpenAI.

Q: Can Pydantic AI agents call external tools or APIs? A: Yes. Tools are defined as typed Python functions decorated with @agent.tool. Arguments and return values are validated against Pydantic schemas, so tool interactions carry the same type guarantees as the agent’s final output.