Pydantic AI

PydanticAI — Typed AI Agents in Python

Overview

Use this skill when you need a Python agent that should:

• return validated structured results instead of free-form text
• call tools through typed arguments
• keep runtime state out of prompts via dependency injection
• remain testable without relying on live model calls for every change
• switch models or providers with minimal application rewrites

PydanticAI is most useful when correctness, schema validation, and maintainability matter more than a quick prompt-only prototype.

This enhanced version preserves the original skill identity while converting the workflow into an execution-oriented guide. Use the support pack when you need deeper runtime practices, a worked example, or a preflight environment check.

When to Use

Use this skill when:

• the user is building Python-based AI agents or assistants
• outputs must validate into a Python or Pydantic type
• tools need explicit argument contracts
• external clients, config, request context, or service handles should be injected rather than hidden in globals
• the user mentions Agent, result_type, tools, RunContext, retries, testing, evals, or provider switching

Do not use this skill as the first choice when:

• the task is a simple one-shot prompt with no typed output requirements
• the user needs a JavaScript-first or browser-only agent framework
• the system depends on broad, free-form tool schemas or uncontrolled side effects
• provider-specific features are more important than portability

Operating Table

Workflow

1. Confirm the task really needs typed agent behavior rather than a plain prompt.
2. Install PydanticAI and the provider-specific extras you actually need.
3. Define a strict result model before writing prompts that assume a response shape.
4. Build a minimal agent that returns one validated result.
5. Add tools as narrow typed functions; keep side effects explicit.
6. Inject runtime state through dependencies instead of prompt text or globals.
7. Test schema behavior and business logic locally.
8. Run representative eval cases before shipping prompt, tool, or model changes.
9. Add instrumentation or tracing during development so validation and tool failures are observable.

Step 1: Installation

Install the base library plus the provider extras required for the model you plan to use.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install "pydantic-ai-slim[openai]"

Provider extras vary by backend. Keep these boundaries explicit:

• OpenAI-style usage requires the matching extra and credentials
• other providers may require different extras, model identifiers, or environment variables
• feature parity is not guaranteed across providers even if PydanticAI exposes a unified API

Recommended preflight checks:

• Python is supported by your project and environment
• pydantic_ai imports cleanly
• the provider extra is installed
• required API credentials are present in environment variables
• the configured model identifier is valid for that provider/account

Run the included preflight script before debugging agent logic:

python scripts/validate-runtime.py --provider openai --require-env OPENAI_API_KEY

Step 2: A Minimal Agent

Start with one agent, one prompt, one typed result.

from pydantic import BaseModel, Field
from pydantic_ai import Agent


class SupportAnswer(BaseModel):
    answer: str = Field(description="Direct response to the user question")
    confidence: float = Field(ge=0.0, le=1.0)


agent = Agent(
    "openai:gpt-4o-mini",
    result_type=SupportAnswer,
    system_prompt=(
        "Answer the user briefly and return a confidence score between 0 and 1."
    ),
)

result = agent.run_sync("How do I reset my password?")
print(result.output)

Good first-run target:

• no tools
• no hidden state
• one small result model
• one known-good model string

If this does not validate, fix the schema or provider setup before adding complexity.

Structured Outputs and Result Models

Prefer result_type and schema-backed outputs over parsing free-form text.

Recommended pattern

• model the output with BaseModel, dataclasses, or other supported typed structures
• encode business constraints directly in the schema
• use validators for ranges, enums, formatting, or cross-field rules when needed
• keep the first version of the schema small

Avoid

• regex parsing model prose into fields
• calling json.loads() on arbitrary unvalidated text if a typed result can be enforced
• large optional-heavy schemas when the task only needs a few fields
• pushing validation entirely downstream into application code

Practical rules

• use explicit field descriptions when the model may confuse similar fields
• prefer enums, literals, bounded numbers, and constrained strings where appropriate
• if validation fails repeatedly, simplify the response contract before increasing prompt complexity

See references/runtime-practices.md for schema design rules and failure handling.

Tools and Dependency Injection

Design tools as narrow typed functions

A good tool:

• has one responsibility
• accepts a small, typed argument set
• returns a predictable value shape
• does not hide side effects
• can be tested independently

A risky tool:

• accepts a large unbounded blob
• mixes lookup, mutation, and formatting in one function
• depends on module globals or ambient state
• returns inconsistent structures