PydanticAI: Recipes
Practical code examples for common scenarios — customer support, multi-agent pipelines, RAG, streaming, memory, error recovery, research agents, batch processing, node inspection, XML prompt enrichment, Capability bundles, WebSearch/WebFetch, HandleDeferredToolCalls, ProcessEventStream.
Verified against pydantic-ai 2.68.0 (checked 2026-11-19); first written for 1.107.0 (June 2026) and updated for the V2 API.
Purpose: Practical code examples for common scenarios
Recipe 1: Customer Support Chatbot with Database Integration
Section titled “Recipe 1: Customer Support Chatbot with Database Integration”"""Customer support agent that:- Reads the customer database through tools and dynamic instructions- Carries the conversation between turns with `Conversation`- Validates its structured output and asks the model to retry when it falls short"""
from dataclasses import dataclassfrom typing import Literal
from pydantic import BaseModel, Fieldfrom pydantic_ai import Agent, Conversation, RunContext, ModelRetryimport asyncioimport sqlite3from datetime import datetime
# Database setupdef init_database(): """Initialize SQLite database.""" conn = sqlite3.connect(':memory:') cursor = conn.cursor()
cursor.execute(''' CREATE TABLE customers ( id INTEGER PRIMARY KEY, name TEXT, email TEXT, account_status TEXT, issue_history TEXT ) ''')
cursor.execute('INSERT INTO customers VALUES (1, "John Doe", "john@example.com", "active", "None")') cursor.execute('INSERT INTO customers VALUES (2, "Jane Smith", "jane@example.com", "premium", "Payment issue")')
conn.commit() return conn
# Dependencies@dataclassclass SupportDependencies: db_connection: sqlite3.Connection customer_id: int
# Output modelsclass SupportResponse(BaseModel): """Structured support response.""" solution: str = Field(..., description="Detailed solution to customer's problem") category: Literal['technical', 'billing', 'general', 'escalation'] confidence: float = Field(..., ge=0.0, le=1.0) next_steps: list[str] = Field(..., description="Recommended next steps")
# Create agentsupport_agent = Agent( 'openai:gpt-6.1-sol', deps_type=SupportDependencies, output_type=SupportResponse, name='CustomerSupportAgent')
# Instructions with dynamic context (re-evaluated on every run)@support_agent.instructionsasync def customer_context(ctx: RunContext[SupportDependencies]) -> str: """Fetch customer context and build system prompt."""
cursor = ctx.deps.db_connection.cursor() cursor.execute( 'SELECT name, email, account_status FROM customers WHERE id = ?', (ctx.deps.customer_id,) )
customer = cursor.fetchone()
if not customer: return "You are a helpful customer support agent."
name, email, status = customer
return f"""You are a professional customer support representative.
Customer Profile:- Name: {name}- Email: {email}- Account Status: {status}
Guidelines:1. Be empathetic and professional2. Provide clear, actionable solutions3. For premium customers, prioritise faster resolution4. Escalate if the issue is outside your scope"""
# Tools for agents@support_agent.toolasync def get_customer_history( ctx: RunContext[SupportDependencies], limit: int = 5) -> str: """Retrieve customer's issue history."""
cursor = ctx.deps.db_connection.cursor() cursor.execute( 'SELECT issue_history FROM customers WHERE id = ?', (ctx.deps.customer_id,) )
result = cursor.fetchone() return result[0] if result else "No history available"
@support_agent.toolasync def create_support_ticket( ctx: RunContext[SupportDependencies], issue_summary: str, priority: str = 'normal') -> str: """Create a support ticket for escalation."""
ticket_id = f"TICKET_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
return f"Created ticket {ticket_id} with priority {priority}"
# Output validator@support_agent.output_validatorasync def validate_response( ctx: RunContext[SupportDependencies], output: SupportResponse) -> SupportResponse: """Validate support response quality."""
if len(output.solution) < 50: raise ModelRetry( "Please provide a more detailed solution (at least 50 characters)." )
if output.confidence < 0.5: raise ModelRetry( "Your confidence is low. Please reconsider your response or escalate." )
return output
# Main executionasync def handle_customer_issue( conn: sqlite3.Connection, customer_id: int, issue: str, conversation: Conversation | None = None) -> tuple[SupportResponse, Conversation]: """Handle one customer message; pass the returned conversation back in for the next one.""" result = await support_agent.run( issue, deps=SupportDependencies(db_connection=conn, customer_id=customer_id), conversation=conversation, ) return result.output, result.conversation
async def main(): conn = init_database() try: response, conversation = await handle_customer_issue(conn, 1, 'I was charged twice for my last purchase!') print(f"Solution: {response.solution}") print(f"Category: {response.category}")
# Follow-up in the same conversation: the model sees the earlier exchange response, conversation = await handle_customer_issue(conn, 1, 'How long will the refund take?', conversation) print(f"Follow-up: {response.solution}") finally: conn.close()
if __name__ == '__main__': asyncio.run(main())In a web service, store conversation (via ConversationTypeAdapter) between requests instead of holding it in memory.
Recipe 2: Multi-Agent Workflow - Research & Writing Pipeline
Section titled “Recipe 2: Multi-Agent Workflow - Research & Writing Pipeline”"""Multi-agent system where agents specialise in different tasks:1. ResearchAgent: Gathers information2. WriterAgent: Structures and writes content3. EditorAgent: Reviews and refines"""
import asynciofrom pydantic_ai import Agent, RunContextfrom dataclasses import dataclassfrom pydantic import BaseModel
@dataclassclass SharedContext: """Shared context between agents.""" topic: str research_notes: str = "" draft_content: str = "" feedback: str = ""
# Research Agentresearch_agent = Agent( 'openai:gpt-6.1-sol', name='ResearchAgent', instructions='You are a research specialist. Gather comprehensive information on topics.')
@research_agent.tool_plaindef search_knowledge_base(query: str) -> str: """Search internal knowledge base.""" # Simulate knowledge base search return f"Found articles about '{query}' in the knowledge base."
async def research_phase(context: SharedContext) -> str: """Research phase of the pipeline."""
research_prompt = f""" Research the following topic comprehensively: Topic: {context.topic}
Provide: 1. Key facts and findings 2. Recent developments 3. Expert perspectives 4. Credible sources """
result = await research_agent.run(research_prompt) context.research_notes = result.output return result.output
# Writer Agentclass Article(BaseModel): title: str introduction: str sections: list[dict] # {'heading': str, 'content': str} conclusion: str
writer_agent = Agent( 'openai:gpt-6.1-sol', output_type=Article, name='WriterAgent', instructions='You are a technical writer. Structure information into clear, engaging articles.')
async def writing_phase(context: SharedContext) -> Article: """Writing phase using research notes."""
writing_prompt = f""" Based on this research: {context.research_notes}
Write a well-structured article on: {context.topic}
Structure: - Title (catchy and descriptive) - Introduction (hook the reader) - 3-4 main sections with clear headings - Conclusion (key takeaways) """
result = await writer_agent.run(writing_prompt) context.draft_content = str(result.output) return result.output
# Editor Agentclass EditedArticle(BaseModel): original: Article suggestions: list[str] grammar_issues: list[str] improvements: str
editor_agent = Agent( 'openai:gpt-6.1-sol', output_type=EditedArticle, name='EditorAgent', instructions='You are a professional editor. Review content for clarity, grammar, and impact.')
async def editing_phase(context: SharedContext, article: Article) -> EditedArticle: """Editing phase for quality assurance."""
editing_prompt = f""" Review this article: {context.draft_content}
Provide: 1. Improvement suggestions for clarity 2. Grammar and spelling issues 3. Overall quality assessment 4. Recommendation for publication """
result = await editor_agent.run(editing_prompt) return result.output
# Orchestrate pipelineasync def research_and_write_pipeline(topic: str) -> Article: """Complete research-to-publication pipeline."""
context = SharedContext(topic=topic)
print("Research phase...") research = await research_phase(context) print(f"Research complete. Found: {len(research)} characters")
print("Writing phase...") article = await writing_phase(context) print(f"Draft complete: {article.title}")
print("Editing phase...") edited = await editing_phase(context, article) print(f"Feedback: {edited.improvements}")
return article
# Usageif __name__ == '__main__': article = asyncio.run( research_and_write_pipeline("Type Safety in Python") ) print(f"\nFinal article: {article.title}")Recipe 3: RAG (Retrieval-Augmented Generation) with Vector Search
Section titled “Recipe 3: RAG (Retrieval-Augmented Generation) with Vector Search”"""RAG pattern combining semantic search with LLM generation.Requires: PostgreSQL with the pgvector extension; pip install asyncpg pgvector"""
from pydantic_ai import Agent, Embedder, RunContextfrom dataclasses import dataclassimport asyncpgfrom pgvector.asyncpg import register_vectorfrom pydantic import BaseModel
@dataclassclass RAGDependencies: """RAG system dependencies.""" db_pool: asyncpg.Pool embedder: Embedder
class RAGResponse(BaseModel): answer: str sources: list[str] confidence: float
rag_agent = Agent( 'openai:gpt-6.1-sol', deps_type=RAGDependencies, output_type=RAGResponse, name='RAGAgent')
@rag_agent.toolasync def retrieve_documents( ctx: RunContext[RAGDependencies], query: str, top_k: int = 5) -> str: """Retrieve relevant documents using vector search."""
# Embed the query with the same model that embedded the documents result = await ctx.deps.embedder.embed_query(query) query_embedding = result.embeddings[0]
# Search for similar documents using pgvector async with ctx.deps.db_pool.acquire() as conn: rows = await conn.fetch(''' SELECT id, title, content, 1 - (embedding <=> $1) AS similarity FROM documents ORDER BY embedding <=> $1 -- order by distance so a pgvector index can be used LIMIT $2 ''', query_embedding, top_k)
# Format retrieved documents formatted_docs = [] for row in rows: formatted_docs.append( f"[{row['title']}]\n{row['content']}\n" )
return "\n\n".join(formatted_docs)
async def rag_query( query: str, db_pool: asyncpg.Pool, embedder: Embedder) -> RAGResponse: """Execute RAG query."""
deps = RAGDependencies(db_pool=db_pool, embedder=embedder)
result = await rag_agent.run(query, deps=deps) return result.output
# Usageasync def main(): # Initialize database pool # register_vector teaches asyncpg to send Python lists as pgvector values pool = await asyncpg.create_pool('postgresql://localhost/documents', init=register_vector) embedder = Embedder('openai:text-embedding-3-small') # see the Embeddings page for other providers
try: response = await rag_query( "How do I implement type safety in Python?", pool, embedder )
print(f"Answer: {response.answer}") print(f"Sources: {response.sources}") print(f"Confidence: {response.confidence}")
finally: await pool.close()Recipe 4: Streaming Agent with Real-Time Response
Section titled “Recipe 4: Streaming Agent with Real-Time Response”Two Server-Sent Events endpoints: one streams text deltas, the other streams partial structured output followed by the validated result. Each SSE message is a data: <json> line followed by a blank line, which is what the browser’s EventSource expects.
"""Real-time streaming agent for web frontends.Returns tokens as they arrive for immediate UI updates."""
import json
from fastapi import FastAPIfrom fastapi.responses import StreamingResponsefrom pydantic import BaseModelfrom pydantic_ai import Agent
app = FastAPI()agent = Agent('openai:gpt-6.1-sol')
class Answer(BaseModel): answer: str follow_up_questions: list[str] = [] # a default lets partial answers stream before this arrives
structured_agent = Agent('openai:gpt-6.1-sol', output_type=Answer)
def sse(payload: dict) -> str: return f'data: {json.dumps(payload)}\n\n'
@app.get('/api/chat/stream')async def chat_stream(message: str): """Stream the reply text as it is generated."""
async def stream_generator(): async with agent.run_stream(message) as response: async for delta in response.stream_text(delta=True): # only the new text each time yield sse({'type': 'text_delta', 'data': delta}) yield sse({'type': 'done'})
return StreamingResponse(stream_generator(), media_type='text/event-stream')
@app.get('/api/chat/structured-stream')async def structured_stream(message: str): """Stream partial structured output, then the validated result."""
async def event_stream(): async with structured_agent.run_stream(message) as response: # stream_text() only works for text output; structured output streams with stream_output() async for partial in response.stream_output(): yield sse({'type': 'partial', 'data': partial.model_dump()}) final = await response.get_output() # runs output validators yield sse({'type': 'final_result', 'data': final.model_dump()})
return StreamingResponse(event_stream(), media_type='text/event-stream')
# Frontend JavaScriptjavascript_example = """const source = new EventSource('/api/chat/stream?message=' + encodeURIComponent('Hello'));source.onmessage = (event) => { const msg = JSON.parse(event.data); if (msg.type === 'text_delta') document.getElementById('response').textContent += msg.data; if (msg.type === 'done') source.close();};source.onerror = () => source.close();"""EventSource can only make GET requests, hence the query parameter; use fetch() with a streamed body reader if you need POST. For the AG-UI and Vercel AI SDK protocols, use the built-in adapters instead of a hand-rolled format.
Recipe 5: Agent with Persistent Memory
Section titled “Recipe 5: Agent with Persistent Memory”"""Agent that maintains conversation memory across sessions.Uses PostgreSQL for persistence; assumes a tableuser_memory(user_id, session_id, key, value, expires_at, updated_at) with UNIQUE (user_id, key)."""
from pydantic_ai import Agent, RunContextfrom dataclasses import dataclassimport asyncpgfrom datetime import datetime
@dataclassclass MemoryDependencies: db_pool: asyncpg.Pool user_id: int session_id: str
memory_agent = Agent( 'openai:gpt-6.1-sol', deps_type=MemoryDependencies, name='MemoryAgent')
@memory_agent.toolasync def store_memory( ctx: RunContext[MemoryDependencies], key: str, value: str, ttl: int = 86400) -> bool: """Store information in persistent memory."""
async with ctx.deps.db_pool.acquire() as conn: await conn.execute(''' INSERT INTO user_memory (user_id, session_id, key, value, expires_at) VALUES ($1, $2, $3, $4, NOW() + INTERVAL '1 second' * $5) ON CONFLICT (user_id, key) DO UPDATE SET value = $4, expires_at = NOW() + INTERVAL '1 second' * $5, updated_at = NOW() ''', ctx.deps.user_id, ctx.deps.session_id, key, value, ttl)
return True
@memory_agent.toolasync def recall_memory( ctx: RunContext[MemoryDependencies], key: str | None = None) -> dict: """Recall stored information."""
async with ctx.deps.db_pool.acquire() as conn: if key: row = await conn.fetchrow(''' SELECT key, value FROM user_memory WHERE user_id = $1 AND key = $2 AND expires_at > NOW() ''', ctx.deps.user_id, key)
return {key: row['value']} if row else {} else: rows = await conn.fetch(''' SELECT key, value FROM user_memory WHERE user_id = $1 AND expires_at > NOW() ''', ctx.deps.user_id)
return {row['key']: row['value'] for row in rows}
@memory_agent.instructions # re-evaluated on every run, so new memories appear next turnasync def memory_aware_prompt(ctx: RunContext[MemoryDependencies]) -> str: """Include user's memory in the instructions."""
memories = await recall_memory(ctx)
memory_str = "\n".join([f"- {k}: {v}" for k, v in memories.items()])
return f""" You have access to the user's persistent memory: {memory_str if memory_str else "No stored memories yet"}
Feel free to reference or update this memory during conversation. """
async def conversational_agent_with_memory( user_id: int, session_id: str, message: str, db_pool: asyncpg.Pool) -> str: """Run agent with memory capabilities."""
deps = MemoryDependencies( db_pool=db_pool, user_id=user_id, session_id=session_id )
result = await memory_agent.run(message, deps=deps) return result.outputRecipe 6: Error Recovery with Retry Strategies
Section titled “Recipe 6: Error Recovery with Retry Strategies”"""Retry a whole run when the provider fails or the model keeps producing invalid output.Retrying individual HTTP requests is better done by the provider SDK or a retryingtransport (see the error handling page); this wrapper is the outer safety net."""
from pydantic_ai import Agentfrom pydantic_ai.exceptions import ModelAPIError, UnexpectedModelBehaviorfrom typing import Optionalimport asynciofrom enum import Enum
class ErrorRecoveryStrategy(str, Enum): EXPONENTIAL_BACKOFF = 'exponential' LINEAR_BACKOFF = 'linear' IMMEDIATE_RETRY = 'immediate'
class ResilientAgent: def __init__( self, model: str, max_retries: int = 3, strategy: ErrorRecoveryStrategy = ErrorRecoveryStrategy.EXPONENTIAL_BACKOFF ): self.agent = Agent(model) self.max_retries = max_retries self.strategy = strategy
def _calculate_backoff(self, attempt: int) -> float: """Calculate backoff time based on strategy."""
if self.strategy == ErrorRecoveryStrategy.EXPONENTIAL_BACKOFF: return 2 ** attempt # 1, 2, 4, 8, ... elif self.strategy == ErrorRecoveryStrategy.LINEAR_BACKOFF: return attempt # 1, 2, 3, 4, ... else: return 0 # Immediate retry
async def run_with_recovery(self, prompt: str) -> Optional[str]: """Run agent with automatic recovery."""
last_error = None
for attempt in range(self.max_retries): try: result = await self.agent.run(prompt) return result.output
except (ModelAPIError, UnexpectedModelBehavior) as e: # not UserError: a bug won't fix itself last_error = e
if attempt < self.max_retries - 1: backoff = self._calculate_backoff(attempt) print(f"Attempt {attempt + 1} failed. Retrying in {backoff}s...") await asyncio.sleep(backoff)
# All retries exhausted print(f"All retries failed. Last error: {last_error}") return None
# Usageresilient = ResilientAgent( 'openai:gpt-6.1-sol', max_retries=3, strategy=ErrorRecoveryStrategy.EXPONENTIAL_BACKOFF)
result = asyncio.run( resilient.run_with_recovery("Analyse this data: ..."))Recipe 7: Research Agent with common_tools (DuckDuckGo + web fetch)
Section titled “Recipe 7: Research Agent with common_tools (DuckDuckGo + web fetch)”"""Research agent that searches the web then fetches and summarises the top result.Requires: pip install "pydantic-ai-slim[duckduckgo,web-fetch]""""
import asynciofrom pydantic import BaseModel, Fieldfrom pydantic_ai import Agentfrom pydantic_ai.common_tools.duckduckgo import duckduckgo_search_toolfrom pydantic_ai.common_tools.web_fetch import web_fetch_tool
class ResearchSummary(BaseModel): topic: str key_findings: list[str] = Field(..., min_length=2, description='At least 2 bullet findings') sources_consulted: list[str] = Field(..., description='URLs fetched during research') confidence: float = Field(..., ge=0.0, le=1.0)
research_agent = Agent( 'openai:gpt-6.1-sol', output_type=ResearchSummary, tools=[ duckduckgo_search_tool(max_results=3), web_fetch_tool(max_content_length=4000, timeout=15), ], instructions=( 'You are a research assistant. ' '1. Use duckduckgo_search to find relevant URLs for the topic. ' '2. Use web_fetch on the top 1-2 results to read the actual content. ' '3. Synthesise findings into the structured output.' ),)
async def research(topic: str) -> ResearchSummary: result = await research_agent.run(f'Research: {topic}') return result.output
if __name__ == '__main__': summary = asyncio.run(research('PydanticAI latest features 2026')) print(f'Topic: {summary.topic}') for finding in summary.key_findings: print(f' • {finding}') print(f'Sources: {summary.sources_consulted}') print(f'Confidence: {summary.confidence:.0%}')Recipe 8: Concurrent batch processing with ConcurrencyLimiter
Section titled “Recipe 8: Concurrent batch processing with ConcurrencyLimiter”"""Process a large batch of items in parallel while capping model concurrency.Useful when you have many tasks but want to avoid hitting rate limits."""
import asynciofrom typing import Literal
from pydantic import BaseModelfrom pydantic_ai import Agent, ConcurrencyLimiter, limit_model_concurrencyfrom pydantic_ai.exceptions import ConcurrencyLimitExceeded
class ItemAnalysis(BaseModel): item_id: str category: str sentiment: Literal['positive', 'negative', 'neutral'] score: float
# Shared limiter: max 5 parallel model calls, queue up to 15 moreshared_limiter = ConcurrencyLimiter(max_running=5, max_queued=15, name='batch-pool')model = limit_model_concurrency('openai:gpt-6.1-sol', limiter=shared_limiter)agent = Agent(model, output_type=ItemAnalysis)
async def analyse_item(item_id: str, text: str) -> ItemAnalysis | None: try: result = await agent.run( f'Analyse this customer feedback (item_id={item_id}): {text}' ) return result.output except ConcurrencyLimitExceeded: print(f'[{item_id}] Dropped — queue full') return None
async def process_batch(items: list[dict]) -> list[ItemAnalysis]: tasks = [analyse_item(item['id'], item['text']) for item in items] results = await asyncio.gather(*tasks) return [r for r in results if r is not None]
async def main(): items = [ {'id': f'item-{i}', 'text': f'Sample feedback number {i}. Great product!'} for i in range(30) ] analyses = await process_batch(items) positives = [a for a in analyses if a.sentiment == 'positive'] print(f'Processed {len(analyses)}/30 items, {len(positives)} positive') print(f'Pool status — running: {shared_limiter.running_count}, waiting: {shared_limiter.waiting_count}')
if __name__ == '__main__': asyncio.run(main())Recipe 9: Node-level inspection with AgentRun.iter()
Section titled “Recipe 9: Node-level inspection with AgentRun.iter()”"""Use agent.iter() to record every graph node, measure per-step latency,and inspect tool call arguments before they execute."""
import asyncioimport timefrom pydantic_ai import Agent, RunContextfrom pydantic_graph import Endfrom pydantic_ai.run import AgentRun
agent = Agent('openai:gpt-6.1-sol')
@agent.tool_plaindef get_temperature(city: str) -> float: """Return the current temperature for a city (simulated).""" return 22.0
async def run_with_inspection(prompt: str) -> dict: """Run the agent and collect execution telemetry.""" telemetry = { 'nodes': [], 'step_times_ms': [], 'run_id': None, 'output': None, }
async with agent.iter(prompt) as run: telemetry['run_id'] = run.run_id node = run.next_node
while not isinstance(node, End): node_name = type(node).__name__ t0 = time.monotonic()
# Inspect the node before it executes if hasattr(node, 'request'): telemetry['nodes'].append({'type': node_name, 'has_request': True}) else: telemetry['nodes'].append({'type': node_name})
node = await run.next(node) elapsed_ms = (time.monotonic() - t0) * 1000 telemetry['step_times_ms'].append(round(elapsed_ms, 1))
telemetry['output'] = run.result.output telemetry['total_messages'] = len(run.all_messages())
return telemetry
async def main(): telemetry = await run_with_inspection('What is the temperature in London?') print('run_id:', telemetry['run_id']) for i, (node, ms) in enumerate(zip(telemetry['nodes'], telemetry['step_times_ms'])): print(f' step {i+1}: {node["type"]} — {ms} ms') print('output:', telemetry['output']) print('messages:', telemetry['total_messages'])
if __name__ == '__main__': asyncio.run(main())Recipe 10: Prompt enrichment with format_as_xml
Section titled “Recipe 10: Prompt enrichment with format_as_xml”"""Use format_as_xml to inject structured context (product catalogue, user profile)into the system prompt so the model can reason over it without JSON parsing issues."""
import asynciofrom dataclasses import dataclass, fieldfrom pydantic import BaseModelfrom pydantic_ai import Agent, RunContext, format_as_xml
@dataclassclass Product: id: str name: str price: float category: str in_stock: bool
@dataclassclass ShoppingContext: user_name: str budget: float products: list[Product] = field(default_factory=list)
class Recommendation(BaseModel): recommended_products: list[str] # product IDs reasoning: str total_cost: float
agent = Agent( 'openai:gpt-6.1-sol', deps_type=ShoppingContext, output_type=Recommendation,)
@agent.system_promptasync def inject_catalogue(ctx: RunContext[ShoppingContext]) -> str: catalogue_xml = format_as_xml( ctx.deps.products, root_tag='catalogue', item_tag='product', ) return ( f'You are a shopping assistant for {ctx.deps.user_name}. ' f'Their budget is ${ctx.deps.budget:.2f}.\n\n' f'Available products:\n{catalogue_xml}\n\n' 'Recommend products within the budget and explain your choices.' )
async def main(): context = ShoppingContext( user_name='Alice', budget=50.0, products=[ Product('p1', 'Python Book', 35.0, 'books', True), Product('p2', 'Keyboard', 85.0, 'electronics', True), Product('p3', 'USB Hub', 25.0, 'electronics', True), Product('p4', 'Mouse Pad', 12.0, 'accessories', True), ], )
result = await agent.run( 'What should I buy today?', deps=context, ) rec = result.output print('Recommended:', rec.recommended_products) print('Total cost:', rec.total_cost) print('Reasoning:', rec.reasoning)
if __name__ == '__main__': asyncio.run(main())Recipe 11: Capability Bundle — scoped tool set per user role
Section titled “Recipe 11: Capability Bundle — scoped tool set per user role”"""Demonstrates the `Capability` convenience class: bundle tools, toolsets, andinstructions under a single named capability that can be toggled per run.
Pattern:- Build a 'read-only' and an 'admin' Capability- Inject only the appropriate one based on the caller's role"""
import asynciofrom dataclasses import dataclass
from pydantic_ai import Agent, RunContextfrom pydantic_ai.capabilities import Capabilityfrom pydantic_ai.models.test import TestModel
# --- Capabilities ---
read_cap: Capability = Capability( id='read', description='Read-only data access tools', instructions='You may ONLY read data. Never modify anything.',)
admin_cap: Capability = Capability( id='admin', description='Full CRUD data access tools', instructions='You have full read/write access. Confirm destructive actions.',)
@read_cap.tool_plaindef list_users() -> list[str]: """List all user names.""" return ['alice', 'bob', 'carol']
@read_cap.tool_plaindef get_user(name: str) -> dict: """Get details for a specific user.""" return {'name': name, 'active': True}
@admin_cap.tool_plaindef list_users_admin() -> list[str]: """List all users including suspended accounts.""" return ['alice', 'bob', 'carol', 'suspended_dave']
@admin_cap.tool_plaindef delete_user(name: str) -> str: """Permanently delete a user account.""" return f'User {name!r} deleted.'
@dataclassclass Deps: role: str # 'read' or 'admin'
agent = Agent(TestModel(custom_output_text='Done.'), deps_type=Deps)
async def run_as(role: str, query: str) -> str: cap = admin_cap if role == 'admin' else read_cap result = await agent.run(query, deps=Deps(role=role), capabilities=[cap]) return result.output
async def main() -> None: print(await run_as('read', 'List users')) print(await run_as('admin', 'Delete user bob'))
if __name__ == '__main__': asyncio.run(main())Recipe 12: Web-research agent with WebSearch + WebFetch (native / local fallback)
Section titled “Recipe 12: Web-research agent with WebSearch + WebFetch (native / local fallback)”"""Research agent that combines WebSearch (for discovery) and WebFetch (for full content).Native tools are used where the provider has them. Since 2.0 the capabilities arenative-only unless you pass local=...; here local= opts into DuckDuckGo search and amarkdownify-based fetch for providers without native support. Settings that only anative tool can honour (blocked_domains, enable_citations, ...) raise UserError on thelocal path rather than being dropped, so keep them off if you rely on the fallback.
Requirements (for the local fallback paths): pip install "pydantic-ai-slim[web-fetch,duckduckgo]""""
import asynciofrom pydantic import BaseModelfrom pydantic_ai import Agentfrom pydantic_ai.capabilities import WebSearch, WebFetch
class ResearchSummary(BaseModel): topic: str key_facts: list[str] sources: list[str]
agent = Agent( 'anthropic:claude-sonnet-5-5', # native web search + web fetch output_type=ResearchSummary, system_prompt=( 'You are a research assistant. Use web_search to discover relevant pages, ' 'then web_fetch to read them in full. Summarise the findings.' ), capabilities=[ WebSearch( local='duckduckgo', blocked_domains=['reddit.com', 'twitter.com'], ), WebFetch( local=True, enable_citations=True, max_content_tokens=4096, ), ],)
async def main() -> None: result = await agent.run('Research: What are the latest advances in diffusion models?') summary = result.output print(f'Topic: {summary.topic}') for fact in summary.key_facts: print(f' • {fact}') print('Sources:', summary.sources)
if __name__ == '__main__': asyncio.run(main())Recipe 13: Inline HITL with HandleDeferredToolCalls
Section titled “Recipe 13: Inline HITL with HandleDeferredToolCalls”"""Demonstrates `HandleDeferredToolCalls`: intercept deferred tool calls inline,automatically approve low-risk operations, reject high-risk ones with anexplanation, and let the agent continue without a second invocation."""
import asyncio
from pydantic_ai import Agent, RunContextfrom pydantic_ai.capabilities import HandleDeferredToolCallsfrom pydantic_ai.models.test import TestModelfrom pydantic_ai.toolsets import FunctionToolsetfrom pydantic_ai.tools import DeferredToolRequests, DeferredToolResults, ToolApproved, ToolDenied
LOW_RISK_TOOLS = {'send_notification', 'log_event'}HIGH_RISK_TOOLS = {'delete_record', 'send_email_blast'}
async def approval_handler( ctx: RunContext[object], requests: DeferredToolRequests,) -> DeferredToolResults | None: # requires_approval=True tools arrive in requests.approvals; # externally executed (CallDeferred / ExternalToolset) ones in requests.calls. decisions: dict[str, ToolApproved | ToolDenied] = {}
for call in requests.approvals: if call.tool_name in LOW_RISK_TOOLS: decisions[call.tool_call_id] = ToolApproved() elif call.tool_name in HIGH_RISK_TOOLS: decisions[call.tool_call_id] = ToolDenied( f'Rejected: {call.tool_name} requires manual review' )
if not decisions: return None # leave everything unresolved for the next handler / the caller
return requests.build_results(approvals=decisions)
toolset = FunctionToolset()
@toolset.tool_plain(requires_approval=True)def send_notification(message: str) -> str: """Send a push notification.""" return f'Notification sent: {message}'
@toolset.tool_plain(requires_approval=True)def delete_record(record_id: str) -> str: """Permanently delete a database record.""" return f'Record {record_id} deleted'
agent = Agent( TestModel(custom_output_text='All actions processed.'), toolsets=[toolset], capabilities=[HandleDeferredToolCalls(handler=approval_handler)],)
async def main() -> None: result = await agent.run('Send a notification about the deploy, then delete record #42.') print(result.output)
if __name__ == '__main__': asyncio.run(main())Recipe 14: ProcessEventStream — latency observer + thinking-strip processor
Section titled “Recipe 14: ProcessEventStream — latency observer + thinking-strip processor”"""Shows both forms of ProcessEventStream:1. Observer (async def → None): records first-token latency.2. Processor (async generator): strips ThinkingPart events so downstream consumers never see extended-thinking content."""
import asyncioimport timefrom collections.abc import AsyncIterable, AsyncIterator
from pydantic_ai import Agent, RunContextfrom pydantic_ai.capabilities import ProcessEventStreamfrom pydantic_ai.messages import AgentStreamEvent, PartStartEvent, ThinkingPartfrom pydantic_ai.models.test import TestModel
class LatencyTracker: first_token_ms: float | None = None _start: float = 0.0
def reset(self) -> None: self._start = time.monotonic()
tracker = LatencyTracker()
async def latency_observer( ctx: RunContext[object], stream: AsyncIterable[AgentStreamEvent],) -> None: tracker.reset() async for event in stream: if tracker.first_token_ms is None and isinstance(event, PartStartEvent): tracker.first_token_ms = (time.monotonic() - tracker._start) * 1000
async def strip_thinking( ctx: RunContext[object], stream: AsyncIterable[AgentStreamEvent],) -> AsyncIterator[AgentStreamEvent]: async for event in stream: if isinstance(event, PartStartEvent) and isinstance(event.part, ThinkingPart): continue yield event
agent = Agent( TestModel(custom_output_text='42 is the answer.'), capabilities=[ ProcessEventStream(handler=latency_observer), ProcessEventStream(handler=strip_thinking), ],)
async def main() -> None: result = await agent.run('What is the meaning of life?') print('Output:', result.output) if tracker.first_token_ms is not None: print(f'First-token latency: {tracker.first_token_ms:.1f} ms') else: print('First-token latency: n/a (TestModel)')
if __name__ == '__main__': asyncio.run(main())