Build type-safe AI agents with validated outputs in Python

PydanticAI is a Python agent framework from the Pydantic team that brings the same type-safety and validation guarantees as Pydantic to LLM-based applications. This skill teaches how to build production AI agents with it. The framework supports structured outputs validated with Pydantic models, dependency injection for testability, streamed responses, multi-turn conversations and tool use, across OpenAI, Anthropic, Google Gemini, Groq, Mistral and Ollama.

The skill walks through eight steps:

1. Installation, with extras for OpenAI or Azure OpenAI, Anthropic, Gemini, Groq and Vertex AI.
2. A minimal agent: create an Agent with a model string and system prompt, call run_sync, and read the data and usage from the result.
3. Structured output: pass a result_type Pydantic model, such as a movie review with title, year, rating, summary and a recommended flag, and receive a fully typed instance.
4. Tool use: register functions with the agent tool decorator; the LLM can call them during a run, and the function docstring is sent as the tool description.
5. Dependency injection: give the agent a deps_type, such as a dataclass holding a database and a user ID, and read it in tools through RunContext.
6. Testing: override the model with TestModel to run unit tests without a real LLM, or use FunctionModel for deterministic responses. Test the structure of the result, not the model's exact words.
7. Streaming: use run_stream and stream_text to show progressive output, then read total usage.
8. Multi-turn conversations: take all_messages from one result and pass it as message_history to the next call.

pip install pydantic-ai

Use it when building Python agents that call tools and return structured data, when you need validated typed outputs and not raw strings, when you want unit tests for agent logic without hitting a real LLM, when you want to switch providers without rewriting agents, or when the user asks about Agent, RunContext, ModelRetry or result_type.

The skill lists alternatives in its related skills: a langchain-architecture skill is described as a more flexible but less type-safe framework, and there are separate skills for general LLM application patterns, FastAPI serving and multi-agent orchestration. Its Limitations section says to use it only when the task matches this scope and to ask when inputs or permissions are missing.

The inputs are a model string, a system prompt, an optional result type, an optional dependency type and tools. The output is a typed result whose data attribute holds the validated object.

Three worked examples show patterns. A code review agent returns a quality level of excellent, good, needs_work or poor, plus issues, suggestions and an approved flag, and approves only good or excellent code with no security issues. A retry example uses a result validator that raises ModelRetry when a value exceeds 1000, asking the model to try again. A multi-agent pipeline has a researcher agent produce key points and a conclusion, then a writer agent turn them into a blog post with title, body and meta description.

Best practices: always define a result type with a Pydantic model, use a dataclass for deps, use TestModel in unit tests so CI never hits a real LLM, add result validators for business logic, and use run_stream for long user-facing outputs. Avoid putting secrets in Agent arguments, avoid sharing one agent instance across async tasks when deps differ, and do not catch ValidationError broadly, since ModelRetry handles recoverable output errors.

Security notes: set API keys through environment variables such as OPENAI_API_KEY and ANTHROPIC_API_KEY, validate tool inputs before passing them to external systems, require explicit user confirmation for tools that mutate data, log all_messages for audit trails, and set retries limits to prevent runaway loops.

Common pitfalls and fixes: if validation fails on every response, simplify the result type with Optional and defaults; if a tool is never called, write a clearer docstring; if a dependency is None inside a tool, pass deps on each run call; and inside FastAPI use await agent.run directly rather than asyncio.run.

Python developers building production agents, chatbots or LLM pipelines where correctness and testability matter.