iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To build an AI agent with Pydantic AI 2.0, install the SDK, choose a model provider, define the agent’s instructions and typed inputs and outputs, then run it using the interface that fits your application. Add tools or reusable capabilities only when the task needs them; a single agent is often the simplest starting point.
Pydantic AI is a Python SDK for building agents, not a hosted model. Version 2 became stable on June 23, 2026, and the project’s release page listed v2.54.0, dated October 2, 2026, as its latest stable release when checked on October 7, 2026. Because releases move quickly, check the release page and pin the version you use rather than assuming the examples remain unchanged.
What an agent contains
An agent is the reusable application component that coordinates a model with the behavior and types your program needs. Its contract can include developer instructions, callable tools or toolsets, an optional structured output type, a dependency type, a selected model, and model settings. Pydantic’s agent guide explains these pieces and the available run interfaces.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →- Instructions tell the model what role or task to perform.
- Tools let the model request specific application actions or information.
- Output type can describe a structured result when later code needs predictable data.
- Dependencies carry typed application context into agent execution where appropriate.
- Model and settings determine the provider-backed model and its configuration.
Use types to make the intended dependency and result shapes clearer to your IDE and static type checker. Keep the first agent narrow: define its purpose, expose only the tools it needs, and choose structured output only when downstream code benefits from a defined shape. An agent can be instantiated once for reuse or created dynamically when an application needs different configurations.
#1 Best Overall
Install Pydantic AI and choose a model provider
The official installation guide describes the standard pydantic-ai installation as including core dependencies and libraries for OpenAI, Anthropic, and Google models, alongside integrations such as the CLI, MCP, Evals, Web UI, and Logfire. It also documents optional extras for other providers and integrations, including pydantic-ai[bedrock,temporal], and a slim distribution for installing selected extras.
Confirm the current installation command and provider setup in the official guide before implementing a project. Provider-specific model names, credentials, usage rules, and prices are not universal; choose those from the documentation for the provider and model you actually use. Do not put API secrets in source code—supply them through your application’s secure configuration.
Define the agent’s contract
In a Python application, define the agent around what the rest of the program expects from it. For example, a support workflow might need an answer as plain text, while a routing workflow may need a typed category that application code can inspect. The output choice belongs to the application contract, not to the fact that the system is called an agent.
Free tools Windows power users keep installed
One-click scans. No signup required.
- Write instructions that describe the task and relevant constraints.
- Give the agent only tools required for that task.
- Pass external application context through dependencies when it should be available during execution.
- Specify a structured result type when later code must consume fields predictably.
- Select a model and settings appropriate to the provider and workload.
Keep provider configuration distinct from the agent’s reusable behavior where that makes the application easier to maintain. The SDK supports agents as reusable components, so the same definition can serve repeated calls, while separate agent instances can represent genuinely different configurations.
Choose how to run the agent
Pydantic AI offers interfaces for completed results, incremental output, event streams, and stepwise access to execution. The right choice depends on whether the surrounding code is asynchronous, whether a user interface should update before completion, and whether the application needs to inspect individual steps.
| Interface | Use it when | What it provides |
|---|---|---|
agent.run() |
Your application uses async Python and can wait for completion. | An asynchronous completed result. |
agent.run_sync() |
You need synchronous completion. | A completed result through a synchronous interface. |
agent.run_stream() / run_stream_sync() |
You want incremental output in an async or synchronous context. | Streamed text or structured output. |
agent.run_stream_events() |
Your application needs to consume streamed execution events. | An event iterator. |
agent.iter() |
You need stepwise access to execution rather than only the final result. | Access to the underlying graph’s steps. |
For a basic asynchronous service, start with agent.run() and handle the completed result. Choose a streaming interface when the product should present output progressively. Use agent.iter() when step-level observation or control is part of the workflow, not merely because it is available. The official agent guide documents the interfaces and their current behavior.
Add reusable capabilities when configuration is not enough
A capability packages behavior that can be composed and reused. According to the capabilities guide, a capability can provide tools, lifecycle hooks, instructions, model settings, or model selection. Simple instructions and settings can be supplied directly to an agent or agent specification; capabilities are useful when behavior goes beyond simple configuration or should be reused and extended.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Do not add a capability just to wrap a few static settings. Consider one when the same substantive behavior belongs in several agents or needs a well-defined extension point. This keeps a small agent easy to understand while making shared behavior explicit when the application grows.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Use multiple agents only for distinct responsibilities
The multi-agent guide describes a progression from a single-agent workflow to delegation through a sub-agent tool, programmatic hand-off in application code, and graph-based control flow. These patterns are options, not a requirement for a capable agent.
- Keep one agent when one task and one set of tools are sufficient.
- Delegate to a sub-agent through tools when a distinct specialist task should be callable by the primary agent.
- Use an application-level hand-off when your code, rather than the model, should decide which agent handles the next stage.
- Consider graph-based control flow when coordination has explicit steps or branching that warrants that structure.
Each additional agent introduces another boundary to configure and maintain. Choose a multi-agent design when the responsibilities or control flow justify those moving parts.
Observe behavior and prepare for deployment
For initial implementation, the installation guide points readers toward the agent guide and examples. It also identifies Pydantic Logfire as an observability option for seeing what an agent does, and describes a free tier; confirm current availability and terms on the installation page. The same guide describes Pydantic AI Gateway as an optional way to access models from several providers with one API key. Neither service is required to build every agent.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Before deploying, pin the Pydantic AI version used by your application, verify provider-specific model and credential setup, and decide whether ordinary completion, streaming, or step-level access fits the application’s interaction and debugging needs. Recheck the project’s release history when upgrading, since the documented version changes over time.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
