PydanticAI in Production: Type-Driven Agent Design Patterns

PydanticAI helps teams move from prompt-centric experiments to reliable, schema-driven agent systems.

Why Type-Driven Design Matters

In production, most failures come from malformed outputs and ambiguous tool inputs. Strong typing reduces these failure modes before runtime.

Pattern 1: Strict Structured Outputs

Define explicit response models and reject invalid outputs early.

Benefits:

• Fewer downstream parsing errors
• Better contract stability across services
• Easier regression testing

Pattern 2: Typed Tool Interfaces

Represent tool inputs and outputs as validated models instead of loose dictionaries.

Benefits:

• Clear invocation contracts
• Safer parameter evolution
• Better traceability in logs

Pattern 3: Recoverable Error Flows

Classify errors into validation, retriable execution, and hard business failures.

For each class, define deterministic handling strategies so retries do not become uncontrolled loops.

Pattern 4: Guarded Multi-Step Tasks

For long workflows, validate at every step and persist intermediate state. This improves resilience when model outputs vary.

Operational Checklist

Before going live:

1. Version all core schemas
2. Log validation failures with context
3. Add unit tests for critical tool contracts
4. Monitor error-category trends over time

This approach keeps agent behavior predictable as complexity grows.

---

Type safety is not overhead in agent systems; it is reliability infrastructure.

Tool Calls: From "Looks Right" to "Validates Right"

PydanticAI's real strength is not model wrapping — it makes tool calls part of the same schema validation pipeline. A common failure mode: the model returns "call tool X with args Y", but the args are free-form text. Enforce:

• Declare input schema (Pydantic models) when registering tools
• Return structured ErrorResult on validation failure, not raw exceptions
• Wrap tool outputs in Output models so downstream does not need try/except on unknown dicts

This "validate both ends" pattern minimizes the blast radius of model hallucinations. After adopting it, one fintech team moved from 3 data-dirty tickets per week to roughly 1 per quarter.

Multi-Agent Systems: Roles as Typed Protocols

In multi-agent systems, the biggest maintainability issue is unclear role boundaries — agent A and agent B both claim to have queried the order; whose result wins? PydanticAI supports dependency injection plus Result models that enforce:

• Each role sees only its allowed context slice
• Each role's output must match its role-specific schema
• Cross-role communication goes through a typed message bus, not free strings

In practice this typed protocol turns a 6-role customer-service agent system from "debug by reading logs" to "read the type signature and locate the problem".

Three Things to Do Before Going Live

1. Version your schemas: All Output models get semver. Agent upgrades and consumer upgrades decouple.
2. Make validation failures observable: Each failure logs a span plus context — don't just print. Platforms like Langfuse let you see schema-drift trends directly.
3. Keep the previous schema as fallback: When upgrading the model or changing prompts, retain a fallback path to the prior schema for at least two weeks.

Common Anti-Patterns

• "The model is a black box; the framework handles it" — actually PydanticAI's fallback is explicit; the framework cannot make schema decisions for you.
• "Use Any everywhere for flexibility" — fast short term; changing one field three months later breaks everything.
• "Eval once is enough" — schema evolution inevitably causes behavioral drift; you must rerun regression samples after every change.