Summary: Pydantic AI is an open-source (MIT) Python agent framework that treats structured output as a first-class type: you pass a Pydantic model as output_type, and result.output comes back validated. This tutorial covers install on Python 3.11+, a first typed agent, tools plus dependency injection, and when to add Pydantic Logfire observability. Plan prices below are only for Logfire's hosted Personal / Team / Growth tiers from the official pricing page — the framework itself has no license fee.
What Pydantic AI is (and is not)
Pydantic AI is the agent framework from the same team behind Pydantic Validation. The docs describe it as a typed, extensible agent loop: swap models with a provider:model string, attach tools, and get structured results that match a Python type. It is not a hosted chatbot product. You run agents in your own process — scripts, APIs, durable workers, or a CLI — and you bring your own model provider credentials (or route through Pydantic AI Gateway).
An Agent is the main unit of work. Conceptually it holds instructions, optional function tools, an optional structured output type, a dependency type constraint, a default model, and optional capabilities. Agents are designed for reuse the way a small FastAPI app is: define one, call run / run_sync many times. Multi-agent patterns (delegation through tools, handoffs, graphs) exist, but you do not need them for a first working extractor.
Official docs live at pydantic.dev/docs/ai (the older ai.pydantic.dev host redirects there). Package name on PyPI is pydantic-ai; current release checked for this post was 2.66.0 under the MIT license.
Install Pydantic AI
Requirements from the install guide: Python 3.11+. Prefer a fresh virtual environment.
Step 1: Create a venv (optional but recommended)
python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate
Step 2: Install the full package
pip install pydantic-ai # or uv add pydantic-ai
The full wheel installs the pydantic_ai package plus libraries needed for OpenAI, Anthropic, and Google models, and pulls in CLI, MCP, Evals, Web UI, and Logfire integration extras. To keep a slim environment, use pydantic-ai-slim with only the extras you need, for example pip install "pydantic-ai-slim[openai]" or "pydantic-ai-slim[openai,google,logfire]".
Step 3: Set a provider API key
Pick a model from the Models overview and export the matching environment variable (for OpenAI-style providers that is typically OPENAI_API_KEY). If the provider is missing a key, Pydantic AI raises a clear UserError naming the variable. For unit tests with no network, the docs support Agent('test') via the built-in test model.
Step 4: Confirm import
python -c "from pydantic_ai import Agent; print(Agent)"
Optional examples package: pip install "pydantic-ai[examples]". Optional observability wizard mentioned in the install page: uvx logfire-cli wizard --task pydantic-ai (free Logfire tier; GitHub signup; no credit card).
Your first typed agent with structured output
"Output" in Pydantic AI is the final value from a run — plain text, structured data, an image, or the result of an output function. Structured data is where the framework shines: pass output_type=YourModel and the agent loop forces the model to return data that validates as that type. By default this uses tool calling; you can switch to native or prompted modes when a provider needs it.
Here is the olympics-style example from the Output docs (model id is whatever the docs currently show — always swap to a model you can call):
from pydantic import BaseModel
from pydantic_ai import Agent
class CityLocation(BaseModel):
city: str
country: str
agent = Agent('google:gemini-3.8-flash', output_type=CityLocation)
result = agent.run_sync('Where were the olympics held in 2012?')
print(result.output)
# CityLocation(city='London', country='United Kingdom')
print(result.usage)
result.output is a real CityLocation instance, not a JSON string you parse by hand. result.usage exposes token and cost fields when the provider reports them. If validation fails, the framework can retry within the output retry budget (default one retry) before raising.
Ways to run an agent
agent.run(...)— async, returns a completed run result.agent.run_sync(...)— sync wrapper for scripts and notebooks.agent.run_stream(...)/run_stream_sync(...)— stream text or structured partials.agent.run_stream_events(...)— async iterator over stream events.agent.iter(...)— step through the underlying graph nodes.
For day-one scripts, run_sync is enough. Inside async tools or nested agent calls, use await agent.run(...) instead of nesting run_sync (that raises a UserError to avoid deadlocks).
Important rename if you follow older blog posts: V1's result_type= became output_type= in V2. A TypeError: unexpected keyword argument 'result_type' means you are on V2 APIs with V1 sample code — change the keyword and read the migration map.
Add a tool and inject dependencies
Tools are ordinary Python functions registered with @agent.tool. Type hints become the argument schema; the docstring becomes the tool description the model sees. Arguments are validated before your function runs.
A compact pattern from the overview (sentiment + a review-fetch tool):
from typing import Literal
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext
class Sentiment(BaseModel):
label: Literal['positive', 'negative', 'neutral']
score: float = Field(ge=-1, le=1)
agent = Agent('openai:gpt-6.1-sol', output_type=Sentiment)
@agent.tool
def recent_reviews(ctx: RunContext, product: str) -> list[str]:
"""Fetch recent review snippets for a product."""
return ['The new release fixed everything I complained about!']
result = agent.run_sync('How are people feeling about the Extract app?')
print(result.output)
Dependencies keep secrets and shared clients out of globals. Declare a type with deps_type=... on the Agent, pass an instance as deps=... on run/run_sync, and read it from RunContext as the first parameter of tools or dynamic instructions. A dataclass holding an API key plus an httpx.AsyncClient is the pattern the Dependencies docs use. In tests, override deps (and models) with Agent.override so you never hit a live LLM.
The roulette-wheel example in the Agents guide shows the same idea with deps_type=int and output_type=bool: the tool compares the player's square to ctx.deps, and the run returns a boolean. That is enough to prove type-safe injection without standing up a database.
When to turn on Logfire (and when not to)
Pydantic AI emits OpenTelemetry spans for agent runs, model requests, and tool calls. Pydantic Logfire is the team's hosted (and optionally self-hosted Enterprise) backend for those traces. Instrumentation is optional: if logfire is installed, configured, and logfire.instrument_pydantic_ai() is called, traces go out; otherwise overhead stays near zero.
Use Logfire (or any OTel backend) when you need to answer: why was this run slow, expensive, or wrong? The troubleshooting guide's first advice for non-crashing misbehaviour is to inspect what the model actually saw — instructions, tool schemas, messages, and retries. Logfire makes that a clickable trace; without a backend you can still call result.all_messages() or wrap failures in capture_run_messages().
Minimal hand setup from the Logfire integration page:
uvx logfire-cli auth
uvx logfire-cli init
# then in code:
import logfire
from pydantic_ai import Agent
logfire.configure()
logfire.instrument_pydantic_ai()
agent = Agent('openai:gpt-6.1-sol', name='hello_world_agent',
instructions='Be concise, reply with one sentence.')
print(agent.run_sync('Where does "hello world" come from?').output)
Skip Logfire when you are only practicing with Agent('test'), or when your org already ships OTel elsewhere — the same spans work with other backends. Pydantic AI Gateway (one key, spend limits, failover) is a separate optional layer managed through Logfire; you do not need Gateway to use the open-source Agent API.
Logfire Personal vs Team vs Growth
The open-source pydantic-ai package is free under MIT. The comparison below is only for Pydantic's hosted Logfire / AI observability plans as shown on pydantic.dev/pricing on 2026-11-06. Every listed plan includes a $20/mo usage credit covering 10 million spans, logs, or metrics. Personal hard-caps at that included amount ($0 bill). Team and Growth bill overage at $2 per million additional records, and you can set a price cap.
| Capability | Personal | Team | Growth |
|---|---|---|---|
| Base cost | Free, forever (no credit card) | $49/mo | $249/mo |
| Included telemetry | 10M records/mo, hard-capped at $0 | 10M included, then $2/M | 10M included, then $2/M |
| Seats & guests | 1 seat + 2 read-only guests | 5 seats included ($25/extra seat) + 10 read-only guests | Unlimited seats and guests |
| Projects & retention | 3 projects · 30-day retention | 5 projects | Unlimited projects · up to 90-day retention |
| AI extras | Monitor agents/services/hosts; AI Gateway BYOK (up to 3 credentials) | Adds AI output evaluations + human review; Gateway BYOK (up to 3) | Everything in Team; unlimited BYOK; priority support + boilerplate BAA |
Enterprise is custom (cloud, dedicated, or self-hosted) and is outside this table. Personal is enough for local debugging of Pydantic AI agents; move to Team when several people need write access or you need paid overage instead of an ingest pause.
Editor's note
Who this is for: Python developers who already use Pydantic models and want agents that return typed objects, not free-form chat. Especially useful for extraction, classification, and tool-using workflows you will unit-test.
Who this is not for: people looking for a no-code agent builder, or teams that only need a single chat completion without tools or schemas. Also skip Logfire pricing worry if you only need the OSS library.
Gotchas from the official troubleshooting docs:
- Missing API key → set the env var named in the
UserError, or passapi_key=to the provider. result_type=TypeError → rename tooutput_type=(V2).- Tool exceeded max retries (
UnexpectedModelBehavior) → improve the tool docstring / field descriptions, or raiseretrieson the tool; inspect messages withcapture_run_messages(). - Nested
run_syncinside a sync tool → make the toolasyncandawait agent.run(...). RuntimeError: Event loop is closed→ recreate the agent/model (and HTTP client) after a loop is closed; do not reuse a model bound to a dead connection pool.
FAQ
Is Pydantic AI free?
The open-source framework on PyPI is MIT-licensed and free to use. You still pay your LLM provider for tokens. Pydantic Logfire's Personal plan is free with a hard 10M records/month cap; Team and Growth are paid hosted plans.
Do I have to use Logfire to use Pydantic AI?
No. Logfire integration is optional. Spans are plain OpenTelemetry, so any OTel backend works. Many tutorials never call logfire.configure().
How is this different from CrewAI?
CrewAI focuses on multi-agent crews and flows as product units. Pydantic AI centers on a typed Python Agent with Pydantic output_type, dependency injection, and first-party OTel. You can combine ideas, but the APIs and project layout are different — start from each project's own docs rather than translating one-to-one.
Related posts on lightmind24
- CrewAI Tutorial: Build Your First Multi-Agent Crew — neighbouring multi-agent framework walkthrough.
- Langfuse Playbook: Find Costly and Bad LLM Answers — another observability angle for agent traces.
- Mem0 vs Zep vs Letta: Choosing an AI Agent Memory Layer — memory layers you may add beside a typed agent.
Start with pip install pydantic-ai, one Pydantic model as output_type, and a single run_sync call — then add tools, deps, and traces only when the first typed result is green.
Last verified: 2026-11-06
Sources: Pydantic AI overview, Installation, Agents, Output, Dependencies, Function tools, Logfire integration, Troubleshooting, Pricing, MIT LICENSE, PyPI pydantic-ai 2.66.0.
Image credit: screenshots of public pydantic.dev docs and pricing pages captured for this post; official Logfire weather-agent trace image from Pydantic AI docs (pydantic.dev/docs/ai/img/). Includes no AI-generated image.
댓글
댓글 쓰기