Getting Started with Pydantic AI: Python GenAI Framework

The team behind Pydantic just brought that FastAPI feeling to GenAI development. Pydantic AI V1 launched in September 2025, hitting 14,000 GitHub stars with a simple pitch: building AI agents should feel as clean and type-safe as building FastAPI apps. If you’ve spent time wrestling with LangChain’s layers of abstraction, this framework cuts straight to what matters.

What Makes Pydantic AI Different

Pydantic AI brings Python-native patterns to agent development. No DSLs, no complex chaining abstractions—just type hints, decorators, and dependency injection you already know. The framework validates everything with Pydantic models, catches errors before they hit production, and works with any LLM provider (OpenAI, Anthropic, Gemini, Ollama, and 10+ others).

Here’s the positioning that matters: LangChain is great for demos. Pydantic AI is great for products. Where LangChain accumulated layers of deprecated functionality and multiple ways to do the same thing, Pydantic AI keeps it lean. The entire codebase follows standard Python control flow, making it dramatically easier to reason about what your agent is actually doing.

The model-agnostic design means you’re not locked in. Switch from OpenAI to Anthropic to local Ollama models without rewriting your core logic. That flexibility matters when pricing changes or new models drop.

Core Concepts: Agents, Tools, Dependencies

Agents orchestrate everything. Initialize one with a model, system prompt, and output schema. The agent handles LLM calls, tool execution, and validation. It’s generic and parameterized by dependency and output types, giving you full type safety from input to result.

Tools are functions your LLM can call. Register them with @agent.tool decorators, and the docstring becomes the tool description. Pydantic validates all arguments automatically—if validation fails, the LLM retries. This eliminates an entire class of runtime errors that plague unvalidated agent systems.

Dependencies flow through RunContext objects. Need database connections, API clients, or configuration? Inject them type-safely into tools. This pattern makes testing trivial and keeps your code clean.

Quick-Start: Build a Dice Game Agent

Install Pydantic AI with pip:

pip install pydantic-ai

Here’s a complete working agent that plays a dice game. It calls tools to roll dice and get player names, then responds based on whether the guess matches:

import random
from pydantic_ai import Agent, RunContext

agent = Agent(
    'openai:gpt-4o',
    deps_type=str,
    system_prompt=(
        "You're a dice game. Roll the die and see if the number "
        "matches the user's guess. If so, they're a winner. "
        "Use the player's name in the response."
    ),
)

@agent.tool_plain
def roll_dice() -> str:
    """Roll a six-sided die and return the result."""
    return str(random.randint(1, 6))

@agent.tool
def get_player_name(ctx: RunContext[str]) -> str:
    """Get the player's name."""
    return ctx.deps

result = agent.run_sync('My guess is 4', deps='Anne')
print(result.output)

Break down what’s happening:

• Agent initialization: Specify model (OpenAI GPT-4o here), dependency type (str for player name), and system prompt that defines behavior.
• @agent.tool_plain: Registers stateless functions that don’t need context. The LLM sees the docstring and can call roll_dice() when needed.
• @agent.tool: Context-aware functions access dependencies via RunContext. Here it retrieves the player name.
• Dependency injection: Pass deps='Anne' to make the player name available to tools.
• Execution: run_sync() handles the full conversation flow—LLM decides which tools to call, validates results, and generates a response.

The LLM will call both tools, compare the guess to the rolled number, and respond with something like “Sorry Anne, you rolled a 2. Try again!” The entire flow is type-safe, validated, and debuggable.

Real-World Production Use Cases

Pydantic AI isn’t just for tutorials. Production deployments include customer support agents that query databases and return validated responses with guaranteed schema compliance. E-commerce platforms use it for product recommendation engines where every interaction validates against backend schemas before processing refunds or inventory changes.

Data analysis workflows benefit heavily—agents aggregate data from multiple sources, apply business logic, and generate reports that once took analysts hours to produce manually. Healthcare applications use it for patient summaries and medication reminders, where structured validation ensures HIPAA compliance and data accuracy.

The key advantage in production is validation at every layer. When your agent returns data, you know it conforms to your Pydantic models. No surprises, no runtime schema mismatches.

Getting Started

The official documentation covers advanced features like streaming responses, observability with Pydantic Logfire, and durable execution patterns for long-running workflows. The GitHub repository includes production-ready examples including a bank support agent that demonstrates dependency injection, database access, and structured output.

When to use Pydantic AI: you’re building production applications that need type safety and maintainability, you’re already comfortable with FastAPI or Pydantic patterns, or you need model flexibility to switch providers. When LangChain might be better: rapid prototyping where you need extensive pre-built integrations, or complex document processing workflows with vector stores.

Pydantic AI brings the reliability and developer experience you expect from modern Python frameworks to GenAI development. Install it, try the dice game example, and see how type-safe agent development should feel.