Getting Started with Pydantic AI

Pydantic AI is a Python agent framework designed to help you quickly, confidently, and painlessly build production grade applications and workflows with Generative AI.

tip: FastAPI revolutionized web development by offering an innovative and ergonomic design, built on the foundation of Pydantic Validation and modern Python features like type hints.

Yet despite virtually every Python agent framework and LLM library using Pydantic Validation, when we began to use LLMs in Pydantic Logfire, we couldn’t find anything that gave us the same feeling.

We built Pydantic AI with one simple aim: to bring that FastAPI feeling to GenAI app and agent development.

Pydantic AI ships the agent loop, a composable capabilities system, and built-in capabilities for thinking, web search, web fetch, image generation, MCP, tool search, and more; Pydantic AI Harness is our official library of ready-made capabilities — code execution, file access, guardrails, sub-agent orchestration, and more — that you pick and choose to build coding agents, research assistants, and anything in between.

Why use Pydantic AI Built by the Pydantic Team: Pydantic Validation is the validation layer of the OpenAI SDK, the Google ADK, the Anthropic SDK, LangChain, LlamaIndex, AutoGPT, Transformers, CrewAI, Instructor and many more. Why use the derivative when you can go straight to the source? 😃

Model-agnostic: Supports virtually every model and provider: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, and Perplexity; Azure AI Foundry, Amazon Bedrock, Google Cloud, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel, Nebius, OVHcloud, Alibaba Cloud, SambaNova, and Z.AI. If your favorite model or provider is not listed, you can easily implement a custom model.

Seamless Observability: Tightly integrates with Pydantic Logfire, our general-purpose OpenTelemetry observability platform, for real-time debugging, evals-based performance monitoring, and behavior, tracing, and cost tracking. If you already have an observability platform that supports OTel, you can use that too.

Fully Type-safe: Designed to give your IDE or AI coding agent as much context as possible for auto-completion and type checking, moving entire classes of errors from runtime to write-time for a bit of that Rust “if it compiles, it works” feel.

Powerful Evals: Enables you to systematically test and evaluate the performance and accuracy of the agentic systems you build, and monitor the performance over time in Pydantic Logfire.

Extensible by Design: Build agents from composable capabilities that bundle tools, hooks, instructions, and model settings into reusable units. Use built-in capabilities for web search, thinking, and MCP, pick from the Pydantic AI Harness capability library, build your own, or install third-party capability packages. Define agents entirely in YAML/JSON — no code required.

MCP and UI: Integrates the Model Context Protocol and various UI event stream standards to give your agent access to external tools and data and build interactive applications with streaming event-based communication.

Human-in-the-Loop Tool Approval: Easily lets you flag that certain tool calls require approval before they can proceed, possibly depending on tool call arguments, conversation history, or user preferences.

Durable Execution: Enables you to build durable agents that can preserve their progress across transient API failures and application errors or restarts, and handle long-running, asynchronous, and human-in-the-loop workflows with production-grade reliability.

Streamed Outputs: Provides the ability to stream structured output continuously, with immediate validation, ensuring real time access to generated data.

Graph Support: Provides a powerful way to define graphs using type hints, for use in complex applications where standard control flow can degrade to spaghetti code.

Realistically though, no list is going to be as convincing as giving it a try and seeing how it makes you feel!

Here’s a minimal example of Pydantic AI:

hello_world.py
from pydantic_ai import Agent
agent = Agent(
  'anthropic:claude-sonnet-4-6',
  instructions='Be concise, reply with one sentence.',
)
result = agent.run_sync('Where does "hello world" come from?')
print(result.output)

“”“ The first known use of “hello, world” was in a 1974 textbook about the C programming language. “”“

(This example is complete, it can be run “as is”, assuming you’ve installed the pydantic_ai package)

No API key yet?

You don’t need a provider API key to try Pydantic AI. Pass the built-in ‘test’ model, which runs entirely offline without calling an LLM:

hello_world_test.py from pydantic_ai import Agent agent = Agent(‘test’)
result = agent.run_sync(‘Where does “hello world” come from?’) print(result.output) #> success (no tool calls)

When you’re ready to use a real model, see Models and Providers to pick a provider and set its API key.

The exchange will be very short: Pydantic AI will send the instructions and the user prompt to the LLM, and the model will return a text response.

Not very interesting yet, but we can easily add tools, dynamic instructions, structured outputs, or composable capabilities to build more powerful agents.

Here’s the same agent with thinking and web search capabilities:

hello_world_capabilities.py from pydantic_ai import Agent from pydantic_ai.capabilities import Thinking, WebSearch agent = Agent( ‘anthropic:claude-sonnet-4-6’, instructions=‘Be concise, reply with one sentence.’, capabilities=[Thinking(), WebSearch(local=‘duckduckgo’)], ) result = agent.run_sync(‘What was the mass of the largest meteorite found this year?’) print(result.output) “”“ The largest meteorite recovered this year weighed approximately 7.6 kg, found in the Sahara Desert in January. “”“

Tools & Dependency Injection Example Here is a concise example using Pydantic AI to build a support agent for a bank:

bank_support.py from dataclasses import dataclass from pydantic import BaseModel, Field from pydantic_ai import Agent, RunContext from bank_database import DatabaseConn @dataclass class SupportDependencies:
customer_id: int db: DatabaseConn
class SupportOutput(BaseModel):
support_advice: str = Field(description=‘Advice returned to the customer’) block_card: bool = Field(description=“Whether to block the customer’s card”) risk: int = Field(description=‘Risk level of query’, ge=0, le=10) support_agent = Agent(
‘openai:gpt-5.2’,
deps_type=SupportDependencies, output_type=SupportOutput,
instructions=(
’You are a support agent in our bank, give the ’ ‘customer support and judge the risk level of their query.’ ), ) @support_agent.instructions
async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str: customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id) return f“The customer’s name is {customer_name!r}” @support_agent.tool
async def customer_balance( ctx: RunContext[SupportDependencies], include_pending: bool ) -> float: “”“Returns the customer’s current account balance.”“”
return await ctx.deps.db.customer_balance( id=ctx.deps.customer_id, include_pending=include_pending, ) …
async def main(): deps = SupportDependencies(customer_id=123, db=DatabaseConn()) result = await support_agent.run(‘What is my balance?’, deps=deps)
print(result.output)
“”“ support_advice=‘Hello John, your current account balance, including pending transactions, is $123.45.’ block_card=False risk=1 “”“ result = await support_agent.run(‘I just lost my card!’, deps=deps) print(result.output) “”“ support_advice=“I’m sorry to hear that, John. We are temporarily blocking your card to prevent unauthorized transactions.” block_card=True risk=8 “”“

Complete bank_support.py example

The code included here is incomplete for the sake of brevity (the definition of DatabaseConn is missing); you can find the complete bank_support.py example here.

Instrumentation with Pydantic Logfire Even a simple agent with just a handful of tools can result in a lot of back-and-forth with the LLM, making it nearly impossible to be confident of what’s going on just from reading the code. To understand the flow of the above runs, we can watch the agent in action using Pydantic Logfire.

To do this, we need to set up Logfire, and add the following to our code:

bank_support_with_logfire.py … from pydantic_ai import Agent, RunContext from bank_database import DatabaseConn import logfire logfire.configure()
logfire.instrument_pydantic_ai()
logfire.instrument_sqlite3()
… support_agent = Agent( ‘openai:gpt-5.2’, deps_type=SupportDependencies, output_type=SupportOutput, instructions=( ’You are a support agent in our bank, give the ’ ‘customer support and judge the risk level of their query.’ ), )

That’s enough to get the following view of your agent in action:

Logfire instrumentation for the bank agent — View in Logfire See Monitoring and Performance to learn more.

llms.txt The Pydantic AI documentation is available in the llms.txt format. This format is defined in Markdown and suited for LLMs and AI coding assistants and agents.

Two formats are available:

llms.txt: a file containing a brief description of the project, along with links to the different sections of the documentation. The structure of this file is described in details here. llms-full.txt: Similar to the llms.txt file, but every link content is included. Note that this file may be too large for some LLMs. As of today, these files are not automatically leveraged by IDEs or coding agents, but they will use it if you provide a link or the full text.