building-pydantic-ai-agents

A patterns-and-examples guide for building AI agents with Pydantic AI, a Python agent framework for production-grade generative AI applications. It is intended for when a user mentions Pydantic AI, imports pydantic_ai, or wants to build an agent, add tools or capabilities, defer capability loading, stream output, define agents from YAML, or test agent behavior, and explicitly not for the Pydantic validation library alone or other frameworks such as LangChain, LlamaIndex, CrewAI, or AutoGen. It requires Python 3.10 or newer.

The skill provides tested quick-start patterns covering the core building blocks. These include creating a basic Agent with instructions, adding tools through the tool_plain and tool decorators with a RunContext, producing structured output by passing a Pydantic BaseModel as output_type, injecting dependencies via deps_type and instruction functions, and unit testing with TestModel using the agent's override context. It introduces capabilities as reusable, composable units of agent behavior that bundle tools, hooks, instructions, and model settings (for example Thinking and WebSearch), lifecycle Hooks that intercept model requests, tool calls, and runs through decorators without subclassing, and loading agents from YAML or JSON specs with Agent.from_file. A recurring theme is progressive disclosure, deciding what should load eagerly versus on demand and deferring capability loading for optional instructions, specialist workflows, and long-tail tools the model does not need on most turns.

Rather than inlining everything, the skill uses a task routing table that points to focused references such as Agents Core, Capabilities and Hooks, Capabilities on Demand, Tools Core, Native Tools, Tools Advanced, Input and History, Testing and Debugging, Orchestration and Integrations, and an Architecture and Decision Guide, with guidance to load only the most relevant reference first. Advanced topics span function tools, toolsets, MCP servers, native web search and code execution, multimodal input and message history, multi-agent coordination and graph workflows, durable execution, embeddings, evals, and observability with Logfire.