🎯 What is Pydantic AI?
Pydantic AI is a modern, type-safe framework for building AI agents with native MCP support, perfect for production applications requiring type safety and reliable tool integration.
Type Safety
Structured outputs using Pydantic models with automatic validation
Tool Integration
Native MCP (Model Context Protocol) support for tools - no extra configuration needed
Provider Agnostic
Works with OpenAI, Ollama, Anthropic, and 100+ LLMs via LiteLLM
Async/Await
Built-in async support for high-performance applications
Model Settings
Fine-grained control (max_tokens, top_p, frequency_penalty, etc.)
MCP Native
Direct integration with MCP servers for automatic tool discovery
📦 Installation
uv tool install superoptix --with "superoptix[frameworks-pydantic-ai]"
Includes:
- • pydantic-ai 2.31.x (pinned to >=2.31, <2.32)
- • SuperOptiX core with GEPA 0.1.4
- • MCP SDK (included with pydantic-ai)
Requirements:
- • Python 3.11+
- • Git (for DSPy dependency)
- • Node.js 18+ (for MCP servers, optional)
- • Ollama (for local models, recommended)
🚀 Quick Start
Get up and running with Pydantic AI in minutes
Pull Demo Agent
super agent pull developer
This pulls the developer agent playbook with:
- Ollama model setup (default:
llama3.1:8b) - BDD test scenarios
- Optimization configuration
Configure Model
Uses Ollama by Default! (FREE, no API keys needed!)
# Just install Ollama and run: brew install ollama # macOS ollama pull llama3.1:8b super agent compile developer --framework pydantic-ai super agent run developer --framework pydantic-ai --goal "Implement a user registration API endpoint"
Also Works With Cloud Models: OpenAI GPT-4, Anthropic Claude, Google Gemini, and 100+ providers via LiteLLM
Run the Workflow
# Compile super agent compile developer --framework pydantic-ai # Evaluate baseline performance super agent evaluate developer # Optimize with GEPA (OPTIONAL) super agent compile developer --framework pydantic-ai --optimize super agent optimize developer --auto light --framework pydantic-ai --reflection-lm ollama/llama3.1:8b # Run your optimized agent super agent run developer --framework pydantic-ai --goal "Your task here"
🔌 MCP (Model Context Protocol) Integration
Pydantic AI has native MCP support! Connect to MCP servers directly in your playbook for automatic tool discovery.
Basic MCP Configuration
spec: mcp: enabled: true servers: - name: filesystem type: stdio config: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/private/tmp"] # Use /private/tmp on macOS (or /tmp on Linux) tool_prefix: "fs_" # Optional: prefix to avoid naming conflicts
Note: On macOS, use /private/tmp instead of /tmp. On Linux, use /tmp.
📊 Output Modes
Choose between plain text (default) or structured output mode
Plain Text Mode (Default)
Agent returns natural text responses, which works reliably with smaller models like llama3.1:8b.
# Default mode - no configuration needed # Output is plain text mapped to output fields spec: output_fields: - name: implementation type: str description: Code implementation
Structured Output Mode (Opt-in)
Uses Pydantic BaseModel for type-safe, validated responses. Requires larger models (70b+) for reliable results.
# Enable structured output spec: output_mode: structured # Opt-in output_fields: - name: implementation type: str description: Code implementation required: true optimization: optimize_field_descriptions: true # Optimize field descriptions
⚙️ Model Settings
Fine-grained control over generation parameters
spec: language_model: provider: ollama model: llama3.1:8b max_tokens: 4000 # Default: 4000 (supports detailed responses) top_p: 0.9 # Optional: Nucleus sampling (0.0-1.0) frequency_penalty: 0.0 # Optional: Reduce repetition (-2.0 to 2.0) presence_penalty: 0.0 # Optional: Encourage new topics (-2.0 to 2.0)
max_tokens
Maximum number of tokens in the response
- • Quick: 1000-2000
- • Standard: 2000-4000 (default)
- • Detailed: 4000-8000
- • Very detailed: 8000-16000
top_p
Nucleus sampling threshold (0.0-1.0)
- • 0.9-1.0: More creative, diverse
- • 0.5-0.9: Balanced
- • 0.0-0.5: More focused, deterministic
🎯 GEPA Optimization
What Gets Optimized & How It Works
What Gets Optimized
1. Instructions
The agent's system prompt (built from persona.role, persona.goal, persona.backstory, etc.)
2. MCP Tool Descriptions (Optional)
Tool descriptions for better tool selection and usage (if MCP optimization enabled)
3. Field Descriptions (Optional)
Pydantic model field descriptions for structured output (if field optimization enabled)
How GEPA Optimizes
- 1.Analyzes BDD test scenarios to understand success criteria
- 2.Generates variations of the instructions/tool descriptions
- 3.Tests each variation against your evaluation scenarios
- 4.Selects the best performer based on pass rate
Example: GEPA typically expands instructions to be more explicit and structured, improving agent behavior consistency.
Optimization Commands
⚡ Ultra Fast (~30s-1m, ~3 API calls)
Minimal metric calls for quick verification
super agent optimize my_agent \ --framework pydantic-ai \ --max-metric-calls 3 \ --reflection-lm ollama/llama3.1:8b
Resource Warning: GEPA optimization is resource-intensive and makes many LLM API calls. Use local ollama/llama3.1:8b to avoid API costs. Cloud models (GPT-4, Claude) will incur significant charges ($5-100+ per optimization run).
📊 Optimization Time Guide
| Option | Command | Time | API Calls | Use Case |
|---|---|---|---|---|
| Ultra Fast | --max-metric-calls 3 | ~30s-1m | ~3 | Verify it works |
| Super Light | --max-metric-calls 10 | ~1-2 min | ~10 | Quick test |
| ⭐ Light | --auto light | ~5-10 min | ~50-100 | Recommended |
| Medium | --auto medium | ~15-30 min | ~150-300 | Better results |
| Heavy | --auto heavy | ~30-60 min | ~300-600 | Production ready |
💡 Save money: Use --reflection-lm ollama/llama3.1:8b for free local optimization! Cloud models (GPT-4, Claude) will incur charges (~$0.50-100+ per optimization run).
🔍 Field Description Optimization
Optimize Pydantic model field descriptions for better structured output
What Gets Optimized
GEPA optimizes Pydantic model field descriptions (Field(description=...)) for structured output. This improves the model's understanding of what each output field should contain.
Requires: Structured output mode enabled (output_mode: structured) to use optimized descriptions.
Enable Field Optimization
spec: output_fields: - name: implementation type: string description: The code implementation of the feature required: true optimization: optimize_field_descriptions: true # Enable field description optimization optimizer: name: GEPA params: auto: light reflection_lm: ollama/llama3.1:8b
Example Transformation
Before Optimization:
description: "The code implementation of the feature"
After GEPA Optimization:
description: "Complete, production-ready code implementation with proper imports, error handling, and documentation. Include full function/class definitions, not pseudocode or descriptions."
🔄 Model Configuration
Works with local Ollama models (FREE) or cloud providers
Ollama (Local)
spec: language_model: provider: ollama model: llama3.1:8b # or llama3.1:70b for better quality api_base: http://localhost:11434 max_tokens: 4000 # Adjust based on response length needs top_p: 0.9 # Optional: Control output diversity
Setup:
# Install Ollama brew install ollama # macOS # or download from https://ollama.com # Pull model ollama pull llama3.1:8b # The pipeline automatically: # - Adds 'ollama:' prefix if missing # - Sets OLLAMA_BASE_URL with /v1 suffix # - Uses Pydantic AI's infer_model() for automatic model creation
Other Providers
Pydantic AI supports 100+ providers via LiteLLM. Just specify the provider and model:
spec: language_model: provider: google # or groq, together, bedrock, etc. model: gemini-pro
📋 Complete Playbook Example
Full example with MCP, optimization, and all features
apiVersion: agent/v1 kind: AgentSpec metadata: name: Developer Assistant with MCP id: developer_mcp namespace: software version: 1.0.0 level: genies spec: language_model: provider: ollama model: llama3.1:8b api_base: http://localhost:11434 max_tokens: 4000 top_p: 0.9 input_fields: - name: feature_requirement type: str description: Feature to implement output_fields: - name: implementation type: str description: Code implementation persona: role: Software Developer goal: Write clean, efficient code with file system access backstory: I am an experienced developer with filesystem access through MCP. # MCP Configuration mcp: enabled: true servers: - name: filesystem type: stdio config: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/private/tmp"] # Use /private/tmp on macOS tool_prefix: "fs_" # Tool optimization - use actual MCP server tool names (WITHOUT prefix) optimization: optimize_tool_descriptions: true tool_names: ["read_file", "write_file", "list_directory"] feature_specifications: scenarios: - name: read_config_file input: feature_requirement: Read /private/tmp/config.json and extract the database URL expected_output: implementation: read_file config.json database URL extract optimization: optimize_field_descriptions: true # Optional: for structured output optimizer: name: GEPA params: reflection_lm: ollama/llama3.1:8b # Use forward slash for LiteLLM auto: light
📊 Observability with LogFire
SuperOptiX includes native LogFire integration for Pydantic AI agents
Comprehensive Observability
SuperOptiX provides native LogFire integration for Pydantic AI agents, giving you complete visibility into agent executions, LLM calls, tool usage, and performance metrics.
Tracing
Track agent executions end-to-end
Monitoring
Monitor LLM calls and tool usage
Token Tracking
Track token usage and costs
Dashboards
View traces in LogFire dashboard or local backends (Jaeger)
📈 When to Use Pydantic AI
Choose Pydantic AI when:
- You need type-safe structured outputs
- You want native MCP tool integration
- You prefer modern async/await APIs
- You're building production applications
- You need validated, reliable responses
- You want plain text output mode for smaller models
Compare with Other Frameworks:
DSPy
More optimization targets (all signatures), better for focused tasks
OpenAI SDK
Built-in multi-agent handoffs, session management, guardrails support
CrewAI
Multi-agent teams, role-based collaboration, task delegation
🐛 Troubleshooting
Model Not Found
Symptom: Unknown provider: llama3.1 or ModelHTTPError: 404
Solution: Ensure model string has provider prefix: ollama:llama3.1:8b. Check OLLAMA_BASE_URL includes /v1: http://localhost:11434/v1. Verify Ollama is running: curl http://localhost:11434/api/tags
Low Pass Rate in Evaluation
Symptom: Evaluation scenarios failing
Solution: Check BDD scenario keywords are realistic. Lower threshold in evaluate() method (default is 0.6). Run GEPA optimization to improve instructions. Try different model (llama3.1:70b for more capability). Adjust model settings (max_tokens, top_p).
MCP Server Connection Issues
Symptom: Failed to initialize MCP server or tools not available
Solution: For stdio servers: Verify command exists (which npx). Check args are correct. Ensure MCP server package is installed. For remote servers: Verify URL is accessible. Check network connectivity. General: Check server logs, verify mcp package is installed (uv pip install mcp).
MCP Tool Optimization Fails
Symptom: None of the specified tools found. Available: ['read_file', 'write_file', ...]
Solution: Use actual MCP server tool names WITHOUT prefix. The optimizer queries the MCP server directly, which returns unprefixed tool names. The tool_prefix only affects runtime naming in the agent.
Import Error
Symptom: ModuleNotFoundError: No module named 'pydantic_ai'
Solution: uv tool install superoptix --with "superoptix[frameworks-pydantic-ai]" or uv pip install "pydantic-ai>=2.31,<2.32"
Optimization Takes Too Long
Symptom: Optimization never completes or takes too long
Solution: Use --max-metric-calls 20 for quick test (~1-2 minutes). Use --auto light for balanced speed/quality (~5-10 minutes). Use smaller reflection model: --reflection-lm ollama/llama3.1:8b. Reduce training dataset size (fewer BDD scenarios).
JSON Metadata Instead of Content
Symptom: Agent returns JSON like {'action': 'do_something', 'params': {...}} instead of actual content
Solution: This was fixed in SuperOptiX 0.2.1. The template now uses plain text output mode. Update: uv pip install --upgrade superoptix. Recompile: super agent compile your_agent --framework pydantic-ai
MCP Server Not Initializing
Symptom: No '🛠️ Initialized MCP stdio server' message during run
Solution: Check playbook filename uses underscores: my_agent_playbook.yaml (not hyphens). Verify mcp.enabled: true in playbook. Check MCP server command is correct (command: npx, args: ['-y', '@modelcontextprotocol/server-filesystem', '/private/tmp']).