context-engineering-intro/use-cases/pydantic-ai/README.md

Pydantic AI Context Engineering Template

A comprehensive template for building production-grade AI agents using Pydantic AI with context engineering best practices, tools integration, structured outputs, and comprehensive testing patterns.

🚀 Quick Start - Copy Template

Get started in 2 minutes:

# Clone the context engineering repository
git clone https://github.com/coleam00/Context-Engineering-Intro.git
cd Context-Engineering-Intro/use-cases/pydantic-ai

# 1. Copy this template to your new project
python copy_template.py /path/to/my-agent-project

# 2. Navigate to your project
cd /path/to/my-agent-project

# 3. Start building with the PRP workflow
# Fill out PRPs/INITIAL.md with the agent you want to create

# 4. Generate the PRP based on your detailed requirements (validate the PRP after generating!)
/generate-pydantic-ai-prp PRPs/INITIAL.md

# 5. Execute the PRP to create your Pydantic AI agent
/execute-pydantic-ai-prp PRPs/generated_prp.md

If you are not using Claude Code, you can simply tell your AI coding assistant to use the generate-pydantic-ai-prp and execute-pydantic-ai-prp slash commands in .claude/commands as prompts.

📖 What is This Template?

This template provides everything you need to build sophisticated Pydantic AI agents using proven context engineering workflows. It combines:

• Pydantic AI Best Practices: Type-safe agents with tools, structured outputs, and dependency injection
• Context Engineering Workflows: Proven PRP (Product Requirements Prompts) methodology
• Working Examples: Complete agent implementations you can learn from and extend

🎯 PRP Framework Workflow

This template uses a 3-step context engineering workflow for building AI agents:

1. Define Requirements (PRPs/INITIAL.md)

Start by clearly defining what your agent needs to do:

# Customer Support Agent - Initial Requirements

## Overview
Build an intelligent customer support agent that can handle inquiries, 
access customer data, and escalate issues appropriately.

## Core Requirements
- Multi-turn conversations with context and memory
- Customer authentication and account access
- Account balance and transaction queries
- Payment processing and refund handling
...

2. Generate Implementation Plan

/generate-pydantic-ai-prp PRPs/INITIAL.md

This creates a comprehensive 'Product Requirements Prompts' document that includes:

• Pydantic AI technology research and best practices
• Agent architecture design with tools and dependencies
• Implementation roadmap with validation loops
• Security patterns and production considerations

3. Execute Implementation

/execute-pydantic-ai-prp PRPs/your_agent.md

This implements the complete agent based on the PRP, including:

• Agent creation with proper model provider configuration
• Tool integration with error handling and validation
• Structured output models with Pydantic validation
• Comprehensive testing with TestModel and FunctionModel

📂 Template Structure

pydantic-ai/
├── CLAUDE.md                           # Pydantic AI global development rules
├── copy_template.py                    # Template deployment script
├── .claude/commands/
│   ├── generate-pydantic-ai-prp.md     # PRP generation for agents
│   └── execute-pydantic-ai-prp.md      # PRP execution for agents
├── PRPs/
│   ├── templates/
│   │   └── prp_pydantic_ai_base.md     # Base PRP template for agents
│   └── INITIAL.md                      # Example agent requirements
├── examples/
│   ├── basic_chat_agent/               # Simple conversational agent
│   │   ├── agent.py                    # Agent with memory and context
│   │   └── README.md                   # Usage guide
│   ├── tool_enabled_agent/             # Agent with external tools
│   │   ├── agent.py                    # Web search + calculator tools
│   │   └── requirements.txt            # Dependencies
│   └── testing_examples/               # Comprehensive testing patterns
│       ├── test_agent_patterns.py      # TestModel, FunctionModel examples
│       └── pytest.ini                  # Test configuration
└── README.md                           # This file

🤖 Agent Examples Included

1. Main Agent Reference (examples/main_agent_reference/)

The canonical reference implementation showing proper Pydantic AI patterns:

• Environment-based configuration with settings.py and providers.py
• Clean separation of concerns between email and research agents
• Proper file structure to separate prompts, tools, agents, and Pydantic models
• Tool integration with external APIs (Gmail, Brave Search)

Key Files:

• settings.py: Environment configuration with pydantic-settings
• providers.py: Model provider abstraction with get_llm_model()
• research_agent.py: Multi-tool agent with web search and email integration
• email_agent.py: Specialized agent for Gmail draft creation

2. Basic Chat Agent (examples/basic_chat_agent/)

A simple conversational agent demonstrating core patterns:

• Environment-based model configuration (follows main_agent_reference)
• String output by default (no result_type unless needed)
• System prompts (static and dynamic)
• Conversation memory with dependency injection

Key Features:

• Simple string responses (not structured output)
• Settings-based configuration pattern
• Conversation context tracking
• Clean, minimal implementation

3. Tool-Enabled Agent (examples/tool_enabled_agent/)

An agent with tool integration capabilities:

• Environment-based configuration (follows main_agent_reference)
• String output by default (no unnecessary structure)
• Web search and calculation tools
• Error handling and retry mechanisms

Key Features:

• @agent.tool decorator patterns
• RunContext for dependency injection
• Tool error handling and recovery
• Simple string responses from tools

4. Structured Output Agent (examples/structured_output_agent/)

NEW: Shows when to use result_type for data validation:

• Environment-based configuration (follows main_agent_reference)
• Structured output with Pydantic validation (when specifically needed)
• Data analysis with statistical tools
• Professional report generation

Key Features:

• Demonstrates proper use of result_type
• Pydantic validation for business reports
• Data analysis tools with numerical statistics
• Clear documentation on when to use structured vs string output

5. Testing Examples (examples/testing_examples/)

Comprehensive testing patterns for Pydantic AI agents:

• TestModel for rapid development validation
• FunctionModel for custom behavior testing
• Agent.override() for test isolation
• Pytest fixtures and async testing

Key Features:

• Unit testing without API costs
• Mock dependency injection
• Tool validation and error scenario testing
• Integration testing patterns

📚 Additional Resources

• Official Pydantic AI Documentation: https://ai.pydantic.dev/
• Context Engineering Methodology: See main repository README

🆘 Support & Contributing

• Issues: Report problems with the template or examples
• Improvements: Contribute additional examples or patterns
• Questions: Ask about Pydantic AI integration or context engineering

This template is part of the larger Context Engineering framework. See the main repository for more context engineering templates and methodologies.

---

Ready to build production-grade AI agents? Start with python copy_template.py my-agent-project and follow the PRP workflow! 🚀