Pydantic AIPydantic AI 2.51 · Python 3.10+
Dashboard
0%
1
Curious builder0 XP earned · 300 to level 2
0 daysFinish a lesson to begin
Badge collection0 of 6 unlocked
29 small wins to finish your pathNext lesson →

Agent basics and a first run

An Agent is an object that holds a model and its instructions; run_sync sends it a prompt and returns the answer.

Last updated: 28 Sep, 2026 · Pydantic AI 2.51

After the setup in Installation and setup, you can run an agent with no provider at all. The built-in test model answers with a fixed string, so you see the shape of a run before a real model is involved.

Creating an agent and running it

Two lines make an agent and send it a ticket:

python
from pydantic_ai import Agent

agent = Agent("test", instructions="You answer customer support tickets.")
result = agent.run_sync("I was charged twice for one order")

Running the test model end to end

Example
from pydantic_ai import Agent

agent = Agent("test", instructions="You answer customer support tickets.")
result = agent.run_sync("I was charged twice for one order")
print(result.output)
print(result.usage)

What the run returned

  • result.output is the answer. The test model never reads the prompt, so the text is fixed at success (no tool calls).
  • result.usage counts the run: requests=1 means the agent called the model once.
  • The token counts are estimated by counting words, not billed tokens, so they are plausible rather than exact.

Choosing run_sync, run or run_stream

  • agent.run_sync(prompt) waits for the answer. Use it in scripts.
  • await agent.run(prompt) is the async version, for web servers and handling several tickets at once.
  • agent.run_stream(prompt) gives the answer piece by piece, covered later in the course.

Running an agent asynchronously

Example
import asyncio


async def main():
    result = await agent.run("My parcel never arrived")
    print(result.output)


asyncio.run(main())

The test model vs a hosted model

Test modelHosted model
Reads the promptNo, returns a fixed answerYes
Needs a keyNoYes
Token countsEstimated from wordsBilled by the provider
Use forSeeing a run, wiring, testsReal answers

The first time an agent runs in a process, Pydantic AI prints a start-up banner to standard error with its version and what the agent holds. It stays out of standard output, so piping a run into a file leaves it out. Set PYDANTIC_AI_NO_BANNER=1 in the environment to silence it.

Create agents once
Watch out. An agent is meant to be created once at the top of a module and reused for every request, the way a web app object is. Nothing about a single run is stored on it, so building a new agent per request wastes work.
Try it yourself
  • Change the prompt and run again. Does the output change?
  • Print result.usage.requests and result.usage.input_tokens.
  • Run the agent twice in one script; set PYDANTIC_AI_NO_BANNER=1 and confirm the banner is gone.
PreviousInstallation and setup

You understood something today that you didn't yesterday.