How to run a first Pydantic AI agent

Agents are Pydantic AI's primary interface for interacting with LLMs. For a first run, follow the agents guide: construct one Agent, make one synchronous call with agent.run_sync(), and read result.output. A single agent may control an entire application or component. Multiple agents can also interact to embody more complex workflows.

Copy the model identifier from the guide's example when you run it.

What an agent contains

The Agent class is the container. The guide lists these components:

Instructions: a set of instructions for the LLM, written by the developer.
Function tools and toolsets: functions the LLM may call to get information while generating a response.
Structured output type: the structured datatype the LLM must return at the end of a run, if specified.
Dependency type constraint: dynamic instruction functions, tools, and output functions may all use dependencies when they run.
LLM model: an optional default model associated with the agent. It can also be specified when running the agent.
Model settings: optional defaults to help fine tune requests. They can also be specified when running the agent.
Capabilities: reusable bundles of tools, hooks, instructions, and model settings that extend agent behavior.

Each of those can be configured individually. Capabilities also let you bundle related behavior into reusable units that are easier to compose, share, and load from configuration files.

Agents are generic in their dependency and output types. An agent that required dependencies of type Foobar and produced outputs of type list[str] would have type Agent[Foobar, list[str]]. In practice, the guide says, you should not need to care about that spelling. It should mean your IDE can tell you when the type is right. If you choose static type checking, it should work with Pydantic AI.

Make the first call

There are five ways to run an agent. Start with the synchronous completed call.

agent.run_sync() is a plain, synchronous function that returns a RunResult containing a completed response. Internally, this just calls loop.run_until_complete(self.run()).

The running-agents example constructs an Agent with a model identifier, then calls agent.run_sync() once. The prompt asks for the capital of Italy. The value it prints is result.output, and the page shows 'The capital of Italy is Rome.'

The same example then defines an async function. agent.run() is an async function which returns a RunResult containing a completed response. That call asks for the capital of France, and the page shows 'The capital of France is Paris.' To run the full example, ensure asyncio is imported and add asyncio.run(main()). The guide says no other changes are needed.

Copy the example's literal lines from the agents page, including the model identifier.

Add a dependency, a tool, and a boolean output

The introduction's toy example is the next sample. It simulates a roulette wheel. It expects an integer dependency and produces a boolean output, so the agent has type Agent[int, bool].

Create that agent with the dependency type, the output type, and instructions. The instructions tell the model to use the roulette wheel function to see if the customer has won based on the number they provide. Define a tool that checks if the square is a winner. RunContext is parameterized with the dependency type int. If you got the dependency type wrong, the page says you would get a typing error.

Run the agent with agent.run_sync(), and pass the winning number as the dependency. The example sets that number to 18. In reality, the page says, you might want to use a random number, for example random.randint(0, 36). The published tool does not. It compares the square with the dependency.

result.output will be a boolean indicating if the square is a winner. Pydantic performs the output validation, and it will be typed as a bool since its type is derived from the output_type generic parameter of the agent. The page shows a true result for the bet on square eighteen and a false result for the bet on five. That boolean is the completed output. It is not the string the tool returns to the model.

The other run methods

Stay with agent.run_sync() until result.output is the value you expect. The same section names five ways to run an agent:

agent.run() is the async completed-response call. It returns a RunResult.
agent.run_sync() is the synchronous call above, and also returns a RunResult.
agent.run_stream() is an async context manager which returns a StreamedRunResult, with methods to stream text and structured output as an async iterable. agent.run_stream_sync() is a synchronous variation that returns a StreamedRunResultSync with synchronous versions of the same methods.
agent.run_stream_events() is an async context manager which yields an async iterator over AgentStreamEvent values, ending with an AgentRunResultEvent containing the final run result.
agent.iter() is a context manager which returns an AgentRun, an async iterable over the nodes of the agent's underlying Graph.

You can also pass messages from previous runs to continue a conversation or provide context. The page points that at its messages and chat history section.

One streaming limit matters before you leave the synchronous call. If the model returns both tool calls and text, and the agent's output type is str, the tool calls will not run in streaming mode with the default setting. These dangling tool calls will not be executed unless end_strategy is set to 'graceful' or 'exhaustive'. Even then, their results will not be sent back to the model, because the agent run will already be considered completed. To keep running when the agent performs tool calls, and to stream events from the model response and from tool execution, use agent.run_stream_events() or agent.iter().

agent.run_stream() also takes an optional event_stream_handler for insight into the run before the final output is produced. During a realtime session, that same handler stream can also contain realtime-only RealtimeEvent members. A first completed call does not need that handler. The page goes on to streaming all events, custom events, and graph iteration after you already know how to finish a run.

What to run next

Open the agents guide. Run its synchronous capital-city example, then the roulette example, copying the literal lines from that page. Read result.output both times. On the roulette run, that value is the boolean the page describes, not the string the tool returns.

Sources

Agents