78%
of AI projects fail in production
Unpredictable output that the next system cannot process.
Pattern
Pydantic: The Backbone of Reliable AI Agents
LLMs produce text. Agents need structure. Pydantic sits at the boundary: schemas, coercion, a structured error for everything else. Shape is not truth — but without a contract, production cannot even start.
The argument
Production AI breaks at the output boundary
Most agentic systems that fail do so from unstructured output that downstream code cannot trust — not from a weaker model. Pydantic receives raw text, validates it, coerces what can be fixed, and raises a field-level error for the rest.
78% of AI projects failing in production is this article's industry figure, not a Vstorm client KPI. 100% type-safe means schema-valid — a model can still hallucinate a legal confidence score. 3× debugging is this article's claim for teams without schemas. None of these are STCC triage or Mixam conversion.
3×
more debugging time without schemas
Malformed JSON and type mismatches at handoff boundaries.
100%
Type-safe output at the Pydantic boundary
Every field validated before business logic. Shape, not truth.
An LLM that cannot guarantee its output format is not a tool — it is a liability. Pydantic turns probabilistic text into deterministic contracts.
About this article
A Vstorm engineering article by Kamil Ślimak, Agentic AI Engineer. It sits on the case-study route because that is where it first shipped. How we sell and build this stack: PydanticAI development services. A listed client graph that uses PydanticAI in production is the US manufacturing text-to-SQL build — eight steps, 473+ columns. Do not read this page's 78% onto that engagement.
What changes
From string manipulation to a typed interface
- Schema-first: models exist before the first prompt
- Validation at every agent-to-agent handoff
- JSON Schema export into OpenAI response_format or Anthropic tools
- Instructor-style retry when validation fails — a parse error becomes another call
- Field validators for domain rules at the boundary, not three layers down
The problem
Production AI breaks at the output boundary
Pydantic started as a Python validation library. In agentic systems — where LLM output flows into business logic, tools, and multi-step pipelines — it is a reliability primitive. Models still omit fields, mistype values, or invent keys. In a notebook that is annoying. On financial documents or clinical workflows it is a failure mode.
Better prompting is not the fix. Validation is. The library sits between the model and your code: receive, validate, coerce, or raise. Skipping that step is rarely a decision. A prototype works. A parse function handles the common cases. Then a new model version, a longer window, an edge case — and the error is six steps downstream of a missing JSON field.
How production teams use it
Schema first. Validate at every handoff. Retry on failure.
Proof of Value is a schema the model must satisfy — not a prompt that usually looks like JSON.
Schema-first design
Define Pydantic models before writing a prompt. The schema is the spec for the model and for the business logic. A schema change surfaces mismatches immediately.
- Typed BaseModel
- JSON Schema export
- Prompt after the spec
Proof of Value at the handoff
Every agent-to-agent pass goes through a Pydantic model. Agents stay loosely coupled and independently testable. Failures raise with field-level detail instead of dying in a later try/except.
- Shared contracts
- Immediate validation errors
- Independent tests
Retry, then evaluate truth separately
Instructor or structured-output loops retry a failed parse. That still does not prove the answer is correct. Evaluation, guardrails, and domain checks sit after a valid shape.
- Retry on ValidationError
- Logs you can alert on
- Eval besides schema
How it works
Declare the model. Export the schema. Validate on arrival.
Annotate a BaseModel. Call model_json_schema() and pass it to the provider. Call model_validate_json() on what comes back. Nested models carry tool calls, sub-results, and metadata as one traversable object.
from pydantic import BaseModel, field_validator
from typing import Literal
from uuid import UUID
class AgentResponse(BaseModel):
task_id: UUID
status: Literal["complete", "retry", "failed"]
confidence: float
summary: str
@field_validator("confidence")
def clamp_confidence(cls, v: float) -> float:
assert 0.0 <= v <= 1.0, "confidence must be between 0 and 1"
return v
# Export schema → pass to LLM provider
schema = AgentResponse.model_json_schema()
# Parse and validate LLM response
response = AgentResponse.model_validate_json(llm_output) Define Pydantic model BaseModel subclass with typed fields
↓
Export JSON Schema model.model_json_schema()
↓
Pass schema to LLM provider OpenAI response_format or Anthropic tool definitions
↓
Validate response on arrival model.model_validate_json(llm_output)
Pydantic schema-to-validation flow
Raw LLM output
Pydantic-validated output
Free-form text or loosely formatted JSON — field names, types, and structure vary across model calls.
Data reliability
Strict schema at parse time — every field typed, validated, and coerced before business logic.
Silent failures surface deep in downstream code — hard to trace to the original LLM response.
Error handling
Validation errors raised immediately with field-level detail — log, retry, or escalate cleanly.
Each handoff needs custom parsing — tight coupling that breaks when the shape changes.
Agent interoperability
Shared Pydantic schemas as API contracts — agents stay loosely coupled and independently testable.
Constant defensive coding: try/except, key checks, type casts throughout the pipeline.
Development speed
Schema defined once, reused everywhere — business logic stays readable.
- 01
Type validation
Casts and validates LLM output to Python types — int, float, datetime, UUID, nested models.
- 02
JSON Schema export
Feed the schema into OpenAI function calling, Anthropic tool use, or any structured output API.
- 03
Nested models
Tool calls, sub-results, and metadata in one typed, traversable object.
- 04
Custom validators
@field_validator and @model_validator catch domain rules before they propagate.
- 05
Retry on failure
Instructor or structured-output loops retry the LLM when validation fails — no hand-rolled retry pile.
Honest assessment
Pydantic is not a silver bullet
Pydantic enforces the shape of data. It does not enforce the truth of data. A model can hallucinate a perfectly valid confidence: 0.98 for a wrong answer, and Pydantic will pass it. Validation catches structural failures. It does not replace evaluation, guardrails, or domain checks.
There is also real upfront cost. Union types and discriminated unions for LLM consumption take care. A poorly defined schema can confuse the model and produce worse output than no schema. Teams using Pydantic-based validation in this article report a large drop in parsing failures — cited here as 92% — when handling LLM responses in multi-step pipelines. That is parse reliability, not answer quality.
Why Pydantic works for agents
- Validated schemas eliminate silent type errors across agent handoffs
- JSON Schema export integrates with OpenAI and Anthropic structured output APIs
- Nested models mirror complex tool response shapes without custom parsing
- Field validators enforce domain rules at the boundary, not deep in business logic
- Pydantic v2 (Rust core) adds negligible latency even at high request volumes
- Strong IDE support: autocomplete, inline type errors, fewer runtime surprises
When to think twice
- Schema definitions need upfront modeling — pays off at scale, costly for one-off scripts
- LLMs can still hallucinate within valid schema bounds — validation catches shape, not truth
- Complex union types and discriminated unions can be tricky to define for LLM consumption
Takeaway
Predictability is the precondition for everything else
Pydantic will not prevent hallucinations. It will not replace prompt work or tool design. It makes the parts of the system that touch LLM output honest — contracts at the point where unpredictability enters the pipeline.
If you do not know the shape of what an agent returns, you cannot reliably log it, alert on it, or trace it. Schema validation is not an optimization. It is the foundation. On multi-step agentic workflows, reach for it first — not as the last patch after production breaks.
Work with us
Ready to see how agentic AI stays typed at the output boundary?
Meet directly with our founders and PhD AI engineers. We will walk through real implementations from 30+ agentic projects and the practical steps to integrate them into your workflows.