Building AI agents with PydanticAI

What is an agent?

A plain LLM call is a single question and a single answer. An agent wraps the model in a loop and gives it tools — functions it can decide to call. The model reasons, calls a tool, reads the result, and keeps going until the task is done.

The loop (reason → act → observe) is what makes it an agent. Remove the loop and the tools, and you're back to a single chat message.

What is a tool?

A tool is just a normal Python function you register with the agent. The model sees its name, arguments, and docstring, and decides when to call it. You control what it can actually do.

from pydantic_ai import Agent

agent = Agent("google-gla:gemini-2.0-flash")

@agent.tool_plain
def word_count(text: str) -> int:
    """Return the number of words in the given text."""
    return len(text.split())

The docstring is not a comment — it's the tool's instruction manual for the model. Clear name + clear docstring + typed arguments = the model uses it correctly. Tools are how the model touches the real world: search the web, query a database, run code, hit an API, read a file.

Why an agent beats a single LLM request

The motivation, in one line

What the benchmarks show

The industry measures agents on tasks that require doing, not just talking. A few worth naming in class:

The consistent finding: giving a model tools + a loop lifts task-completion rates far beyond what better prompting alone can do. The gap is the whole reason agents exist.

Your stack: framework, model, harness

Three independent choices. The model and framework are easy to swap — the harness is where the real engineering lives, and it's what actually makes an agent good.

Why the harness is the agent

Two teams can use the identical model and framework and get wildly different results. The gap is the harness — the scaffolding you build around the loop:

Agent architectures

Once you have one agent, the next question is how to combine them. There's a ladder of patterns from a single loop up to teams of specialists — you pick the simplest one that solves your problem.

First distinction: workflow vs. agent

Both are built from the same brick: the augmented LLM — a model with tools, memory, and retrieval (that's your harness). Everything below is just different ways of arranging those bricks.

The core patterns

Scaling up: multi-agent topologies

When one team of specialists isn't enough, these describe how many agents relate to each other. Rule of thumb: default to orchestrator/hierarchical; reach for peer patterns only when you truly need them.

Connecting tools at scale: MCP

Writing every tool by hand doesn't scale. The Model Context Protocol (MCP) is an open standard — think “USB-C for AI tools” — that lets your agent plug into ready-made servers that expose tools and data: GitHub, Slack, databases, the filesystem, a browser, and hundreds more.

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

# Connect to an MCP server (here: a filesystem server started over stdio).
fs = MCPServerStdio("npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."])

agent = Agent("google-gla:gemini-2.0-flash", toolsets=[fs])

async def main():
    async with agent:            # opens & closes the MCP connections
        result = await agent.run("List the Python files here and summarize each.")
        print(result.output)

Getting free tokens for testing

You don't need a credit card to learn this. Two free paths — and a way to cap your usage so an agent loop can't run away.

export GEMINI_API_KEY="your-key-here"

Simple live example

A tiny agent with one tool, a free model, a structured result, and a request cap. This is the full shape of everything we'll build in the workshop.

from pydantic import BaseModel, Field
from pydantic_ai import Agent
from pydantic_ai.usage import UsageLimits
from pydantic_ai.exceptions import UsageLimitExceeded

# 1. Describe the structured answer we want back (validated automatically).
class Answer(BaseModel):
    reasoning: str = Field(description="Short explanation of how we got here")
    result: int = Field(description="The final numeric answer")

# 2. Build the agent. Model id is 'provider:model' — swap it in one line.
#    Reads GEMINI_API_KEY from the environment; nothing secret in the code.
agent = Agent(
    "google-gla:gemini-2.0-flash",
    output_type=Answer,
    system_prompt="You are a precise assistant. Use the tools; do not do math yourself.",
)

# 3. A tool: a normal typed function. The docstring tells the model what it does.
@agent.tool_plain
def add(a: int, b: int) -> int:
    """Add two integers and return the sum."""
    return a + b

# 4. Run it — with a hard ceiling of 5 model requests so the loop can't run away.
try:
    out = agent.run_sync(
        "What is 21 + 21? Use the add tool.",
        usage_limits=UsageLimits(request_limit=5),
    )
    print(out.output.result)      # -> 42
    print(out.output.reasoning)
except UsageLimitExceeded as e:
    print("Hit the request cap:", e)

import os
from openai import AsyncOpenAI
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

client = AsyncOpenAI(
    api_key=os.environ["OPENROUTER_API_KEY"],   # from env, not hard-coded
    base_url="https://openrouter.ai/api/v1",
)
model = OpenAIModel(
    "meta-llama/llama-3.3-70b-instruct:free",     # a free model
    provider=OpenAIProvider(openai_client=client),
)
agent = Agent(model, system_prompt="You are a helpful assistant.")
print(agent.run_sync("Say hello in one word.").output)

What goes wrong — and how the harness guards it

Agents fail in ways a single function never does. Knowing the failure modes is half of building a good harness.

from pydantic_ai import ModelRetry

@agent.tool_plain
def get_user(user_id: int) -> dict:
    """Look up a user by id."""
    user = db.get(user_id)
    if user is None:
        # Don't crash — tell the model to fix its input and try again.
        raise ModelRetry(f"No user with id {user_id}. Ask for a valid id.")
    return user