Pydantic AI: English for Building Type-Safe AI Agents
Learn the English vocabulary for Pydantic AI: agents, tools, structured output, model-agnostic patterns, async agents, and Pydantic models for type-safe AI development.
Pydantic AI brings the type safety and data validation that Python engineers already trust from Pydantic into the world of AI agent development. By expressing agent inputs, outputs, and tool interfaces as Pydantic models, teams can catch errors at development time rather than at runtime in production.
If you are familiar with Pydantic for API validation but are new to its use in AI agents, this guide will help you navigate the vocabulary. These terms come up constantly in documentation, pull request reviews, and architecture discussions.
Key Vocabulary
Agent
In Pydantic AI, an agent is a Python object that wraps a language model call (or a sequence of calls) and enforces a typed contract on inputs and outputs. The agent knows which model to use, what tools are available, what the system prompt is, and what the output type must be.
“We have a triage agent that takes a raw support ticket as input and returns a structured TriageResult model — the agent guarantees that output is always typed and validated.”
Tool
A tool is a Python function registered with an agent that the language model can invoke during its reasoning process. Tools are described to the model via their function signatures and docstrings; Pydantic AI automatically generates the JSON schema for each tool’s parameters from the type annotations.
“We registered a get_customer_account tool on the agent — its type annotations generate the JSON schema automatically, so the model always knows exactly what arguments to pass.”
Structured Output
Structured output means the agent is constrained to return a specific Pydantic model rather than a free-form string. The framework validates the model’s response against the defined schema and raises a typed error if the output does not conform. This is the core value proposition of Pydantic AI over raw LLM calls.
“Switching to structured output eliminated an entire category of parsing bugs — if the model produces malformed JSON, we get a validation error at the agent layer, not a crash somewhere downstream.”
Model-Agnostic
Model-agnostic describes code that is not tied to a specific LLM provider. Pydantic AI is designed to be model-agnostic: you can swap between OpenAI, Anthropic, Gemini, or a local Ollama model by changing one configuration parameter, without rewriting your agent logic.
“Our agents are completely model-agnostic — we swap between Claude and GPT-4 in our tests and the business logic layer doesn’t change at all.”
Async Agent
An async agent is an agent implemented using Python’s async/await pattern, allowing multiple agent runs to execute concurrently without blocking. Pydantic AI supports both synchronous and asynchronous agent execution; async agents are preferred for production servers handling concurrent requests.
“We migrated to async agents when we moved to production — synchronous agent calls were blocking the event loop and causing timeouts under load.”
Pydantic Model (as Output Type)
A Pydantic model used as an output type is a Python class inheriting from BaseModel that defines the structure, types, and validation rules for the agent’s return value. Every field has a type annotation; optional fields have defaults; custom validators can enforce business rules.
“The agent’s output type is a PolicyDecision model with three fields: approved as a boolean, reason as a string, and confidence as a float between 0 and 1 — Pydantic validates all three on every response.”
Dependency Injection
Dependency injection in Pydantic AI is a mechanism for passing external resources — database connections, API clients, configuration — into an agent’s tools and system prompt at run time, without hard-coding them in the agent definition. Dependencies are defined as a typed dataclass and injected via the agent’s deps_type parameter.
“We inject the database connection as a dependency so tools can query customer data without needing global state — this also makes the agent straightforward to test with a mock database.”
Result Validator
A result validator is a function registered with the agent that runs additional validation on the structured output after the Pydantic schema check passes. It can inspect the validated model and raise an error if business rules are violated — for example, checking that a recommended action is in an allowlist, or that a confidence score meets a minimum threshold.
“Pydantic validates the schema, but our result validator checks the business rules — it rejects any policy decision where approved is true but confidence is below 0.7.”
Useful Phrases
- “The agent’s output type enforces the contract at the framework level — if the model doesn’t return valid structured output, the agent retries automatically.”
- “We inject all external dependencies via the deps pattern so tools remain pure functions with no side effects during testing.”
- “Switching models is a one-line change — Pydantic AI’s model-agnostic design means our agent logic is completely decoupled from the provider.”
- “The result validator caught an edge case that Pydantic alone would have missed — the schema was valid, but the business logic was violated.”
- “We run all agents asynchronously — without async, each LLM call would block and our API response times would be unacceptable.”
Common Mistakes
Confusing Pydantic AI with Pydantic
Engineers new to the framework sometimes assume Pydantic AI is just Pydantic with a few extra features. They are distinct projects with different purposes. Pydantic is a general-purpose data validation library. Pydantic AI is an agent framework built on top of Pydantic, specifically for orchestrating LLM calls with typed inputs and outputs. You might say “we use Pydantic AI for our agents and Pydantic for our API request models” to make the distinction clear.
Omitting type annotations on tool functions
A common mistake is defining tool functions without complete type annotations. Pydantic AI generates the JSON schema that the LLM uses to call the tool directly from the type annotations — missing or overly broad types (such as Any or dict) produce poor schemas that cause the model to pass incorrect arguments. Always annotate tool parameters with specific types and use docstrings to describe what each parameter does.
Treating structured output as optional
Engineers migrating from raw LLM calls sometimes use structured output only for “important” responses and return plain strings elsewhere. This creates inconsistency — some code paths are validated, others are not — and undermines the type safety that Pydantic AI provides. The recommended practise is to define a structured output type for every agent, even simple ones, and reserve plain string output only for conversational or freeform use cases where structure genuinely does not apply.
Pydantic AI’s approach to agent development is fundamentally about making implicit contracts explicit. The vocabulary in this guide — structured output, dependency injection, result validators, model-agnostic design — all reflect a philosophy that AI agent behaviour should be as rigorous and predictable as any other software interface. When you can express that philosophy in precise English, you will find that architecture discussions become more productive and your pull request comments become easier to write.