building-pydantic-ai-agents

Building AI Agents with Pydantic AI

Pydantic AI is a Python agent framework for building production-grade Generative AI applications. This skill provides patterns, architecture guidance, and tested code examples for building applications with Pydantic AI.

When to Use This Skill

Invoke this skill when:

• User asks to build an AI agent, create an LLM-powered app, or mentions Pydantic AI
• User wants to add tools, capabilities (thinking, web search), or structured output to an agent
• User asks to define agents from YAML/JSON specs or use template strings
• User wants to stream agent events, delegate between agents, or test agent behavior
• Code imports pydantic_ai or references Pydantic AI classes (Agent, RunContext, Tool)
• User asks about hooks, lifecycle interception, or agent observability with Logfire
• User wants to reach models from several providers with one API key (the Pydantic AI Gateway)
• User wants an agent to run commands or access files in an attached workspace
• The agent design includes optional instructions, specialist workflows, long-tail tools, or any context the model does not need on most turns

Do not use this skill for:

• The Pydantic validation library alone (pydantic/BaseModel without agents)
• Other AI frameworks (LangChain, LlamaIndex, CrewAI, AutoGen)
• General Python development unrelated to AI agents

Quick-Start Patterns

Create a Basic Agent

Start new applications with Logfire instrumentation and prompt caching in place, so the first run is already visible and repeated prompt prefixes are read from the cache (see Set Up Observability and Model Access for credentials and alternatives):

import logfire

from pydantic_ai import Agent
from pydantic_ai.capabilities import Caching

logfire.configure()
logfire.instrument_pydantic_ai()

agent = Agent(
    'anthropic:claude-fable-5-1',
    name='hello_world_agent',
    instructions='Be concise, reply with one sentence.',
    capabilities=[Caching()],
)

result = agent.run_sync('Where does "hello world" come from?')
print(result.output)
"""
The first known use of "hello, world" was in a 1974 textbook about the C programming language.
"""