Getting Started with Pydantic AI

Pydantic AI is a typed Python AI agent framework from the Pydantic team—structured outputs, tools, dependencies, and model swapping with familiar Pydantic validation. Docs: pydantic.dev/docs/ai and ai.pydantic.dev.

After work, its superpower is shape: you declare what the agent must return, and validation catches nonsense before you trust it.

Who this is for

Python learners who like type hints and Pydantic models, or who are tired of parsing free-form LLM text. Basic classes/BaseModel knowledge helps a lot.

Overview: Top 10 AI agent tools for after-work Python.

Steps to start tonight

1. Install

python -m venv .venv && source .venv/bin/activate
pip install pydantic-ai
# or: uv add pydantic-ai

2. Optional: try without a paid key first

Docs mention a built-in 'test' model for offline exercise of tools/outputs. Use it to learn the API, then switch to a real provider key when ready.

3. Run a tiny typed agent

from typing import Literal
from pydantic import BaseModel, Field
from pydantic_ai import Agent

class Sentiment(BaseModel):
    label: Literal['positive', 'negative', 'neutral']
    score: float = Field(ge=-1, le=1)

agent = Agent('openai:gpt-4o-mini', output_type=Sentiment)  # pick a model you have keys for
result = agent.run_sync('Review: the new release fixed everything!')
print(result.output)

Adjust the model string to whatever provider you configured.

4. Add one @agent.tool

Define a tool that returns a short list of fake “reviews” for a product name. Ask the agent about that product. Confirm the tool can be called and result.output still validates as Sentiment.

5. NOTES.md: output_type + tools + deps

Write how output_type differs from “just print the model text.” Peek at dependency injection (deps_type) in the docs for later—do not implement a bank demo tonight.

Tiny exercise (15–25 minutes)

Tighten score rules or labels; feed a clearly negative sentence; confirm validation still holds. If the model fails schema, read the retry behavior in the docs instead of deleting types.

Pitfalls

• Ignoring types. Free-form strings defeat the point of Pydantic AI.
• Jumping to Harness/Coder mega-agents. Core Agent + output_type first.
• Wrong model string / missing key. Fix provider setup before blaming the framework.
• Overbuilding capabilities. Web search, voice, Temporal durability can wait.
• Using outdated import paths. Prefer current pydantic.dev / ai.pydantic.dev docs.

Why this fits after work

Typed outputs reduce late-night “parse the paragraph” pain. One validated model is a complete win for an evening session.

Next step

Better Python typing makes agents easier—Intro to Python Programming.