How to Build an AI Agent with Python

Install pydantic-ai, which pulls in Pydantic itself as a dependency. Export your model provider's API key as an environment variable; Pydantic AI reads it the same way the underlying SDK would. The model string format is 'provider:model-id', so Claude Sonnet is 'anthropic:claude-sonnet-5-5'.

1pip install pydantic-ai
2export ANTHROPIC_API_KEY="sk-ant-..."

Before writing any tool, define what a correct answer looks like as Pydantic models: DayPlan (a day number, a list of activities, and an estimated cost) and Itinerary (a destination, a list of DayPlan, and a total cost). This is the contract the agent's final answer must satisfy, decided before you write a single line of agent logic.

1from pydantic import BaseModel
2
3class DayPlan(BaseModel):
4    day: int
5    activities: list[str]
6    estimated_cost_usd: float
7
8class Itinerary(BaseModel):
9    destination: str
10    days: list[DayPlan]
11    total_cost_usd: float

Deps holds whatever a tool needs to do real work, here a placeholder for an API client, in production a real flights/hotels API wrapper. You'll pass an instance of it into run_sync() later, and every tool's RunContext carries it through ctx.deps. This is the idiomatic alternative to a tool reaching for a module-level client or an API key baked into a closure.

1from dataclasses import dataclass
2
3@dataclass
4class Deps:
5    travel_api_client: object  # swap for a real flights/hotels API client

Each tool takes ctx: RunContext[Deps] as its first parameter, which doesn't appear in the schema sent to the model, then the parameters the model actually fills in. search_flights and search_hotels both read ctx.deps.travel_api_client instead of calling a global. The docstring is still the only thing the model reads to decide when to call each one.

1from pydantic_ai import RunContext
2
3@agent.tool
4def search_flights(ctx: RunContext[Deps], origin: str, destination: str, date: str) -> str:
5    """Search for flights between two cities on a given date. Returns price and duration."""
6    return f"{origin} -> {destination} on {date}: $420, 6h10m nonstop"
7
8@agent.tool
9def search_hotels(ctx: RunContext[Deps], destination: str, nights: int) -> str:
10    """Search for hotels in a destination for a number of nights. Returns name and total price."""
11    return f"Riverside Inn, {destination}: ${120 * nights} for {nights} nights"

Agent() takes the model string, deps_type (the Deps class from step 3), output_type (the Itinerary model from step 2), and a system_prompt. deps_type and output_type are what make this agent type-safe end to end: your IDE and your test suite both know exactly what a call returns.

1from pydantic_ai import Agent
2
3agent = Agent(
4    "anthropic:claude-sonnet-5-5",
5    deps_type=Deps,
6    output_type=Itinerary,
7    system_prompt=(
8        "You are a travel planner. Always search flights and hotels before "
9        "building a day-by-day plan with realistic costs."
10    ),
11)

Call run_sync() with the user's request and a Deps instance. result.output is an Itinerary object, not a string, access result.output.total_cost_usd directly. For production, wrap the call in a try/except for pydantic_ai's result-validation errors (the model gave an answer that doesn't fit your schema after retries) and never call run_sync() from code that's already inside an async event loop, use the async agent.run() there instead.

1deps = Deps(travel_api_client=None)  # swap for a real client
2result = agent.run_sync(
3    "Plan a 3-day trip to Lisbon leaving from Boston on 2026-12-10.",
4    deps=deps,
5)
6print(result.output.destination, result.output.total_cost_usd)
7for day in result.output.days:
8    print(day.day, day.activities, day.estimated_cost_usd)