Guide · Open source
How to use pydantic-ai: install, build a typed agent and run it
Updated · written with AI from the project's own documentation and checked against our catalogue data
Pydantic AI is a Python library for building AI agents, programs where a language model can call tools and return results. This guide shows you how to install it, define an agent with a typed output, add a tool and run it. By the end you will understand how validated, typed results work and where to go next.
Pydantic AIpydantic/pydantic-ai · ★ 21k · MIT Install options & downloads Quick start
- 1Install the library. Run uv add pydantic-ai in your project folder. Python must already be installed.
- 2Define your output type. Write a Pydantic model describing the result shape you need, with typed fields and constraints.
- 3Create the agent. Pass a provider model string and your output_type to Agent.
- 4Add tools. Decorate a function with @agent.tool and give it a clear docstring and typed arguments.
- 5Run and read the output. Call agent.run_sync with a prompt and read result.output.
- 6Try the terminal option. Use clai with uvx to chat with a prebuilt agent without writing code, if you want to explore first.
Install pydantic-ai with uv
The README installs the library with uv, a Python package manager. The project is Python-only, so you need Python installed first. uv is optional, but the README examples use it.
- Prerequisites: Python and uv (optional, used in the README examples)
- The library is Python-only, so it is not usable from other languages
uv add pydantic-aiDefine an agent with a typed output
Pydantic AI validates outputs against Python types. You describe the shape you want with a Pydantic model and pass it as output_type. The README example defines a Sentiment model with a label limited to three values and a score between -1 and 1. Because the run is guaranteed to return that type, your editor, type checker and the model agree on the result.
- Import Agent from pydantic_ai and BaseModel and Field from pydantic
- Pass the model as output_type when you create the Agent
- Choose a model with a provider string such as 'openai:gpt-6.1-sol', as in the README example
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)Add a tool the agent can call
Tools let the model fetch data during a run. Decorate a function with @agent.tool. The function receives a RunContext that carries your dependencies, and the rest of its signature and its docstring become the tool schema. Arguments are validated before your code runs.
- The docstring describes the tool to the model, so write it clearly
- Arguments are validated before the function executes
@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!']Run the agent and read the result
Call run_sync with your prompt for a synchronous run. The result's output attribute holds the typed value. The README comment shows the printed output for its example, which is a Sentiment object rather than a plain string.
- Use agent.run_sync(prompt) in simple scripts
- Read the typed value from result.output
result = agent.run_sync('How are people feeling about the Extract app?')
print(result.output)
#> label='positive' score=0.9Other ways to run an agent
The README says the same agent can run behind a web frontend, in the terminal, on a voice call, on a durable background queue, in GitHub Actions, or as an object you call run() on. It also lists image generation and embeddings in the same package. The README shows a terminal coding agent through the clai command, and durable execution through TemporalDurability, which runs model and tool calls as durable activities inside a Temporal workflow.
- Terminal: run an agent with clai via uvx, as shown in the README
- Durable background work: attach TemporalDurability to run inside a Temporal workflow
- Full documentation is at pydantic.dev/docs/ai
uvx --with "pydantic-ai-harness[coder]" clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-fable-5-1What people use it for
- Extracting structured fields such as sentiment labels and scores from text
- Giving an agent tools that fetch data from your own code during a run
- Switching or falling back between model providers with a small string change
- Running one agent in a web app, a terminal or a background queue
- Building a terminal coding agent with the Pydantic AI Harness
Frequently asked questions
Is pydantic-ai free to use?
Pydantic AI is an open-source library released under the MIT licence, according to the project's repository details. Check the LICENSE file in the repository for the full terms.
What do I need to install pydantic-ai?
You need Python. The README installs the library with uv, using uv add pydantic-ai, and notes that uv is optional. The project is Python-only.
Is pydantic-ai a chat app I can use without coding?
No. Pydantic AI is a code library for Python developers. The README says non-programmers looking for a ready-made chat app should choose something else. You can try the prebuilt terminal agent with clai if you just want to explore.
How is pydantic-ai different from LangChain or LlamaIndex?
The source does not include a detailed comparison. It lists LangChain, LlamaIndex, CrewAI and Instructor as comparable projects. Pydantic AI's distinguishing point in the README is typed, validated output built on Pydantic models, so compare them against your own needs.
Can I switch model providers without rewriting my code?
Yes, according to the README. You change the model provider string, for example from openai to anthropic, and the rest of the agent code stays the same. The README also describes a fallback model for when a provider fails.
Does pydantic-ai only work with OpenAI?
No. The README examples use several providers, including OpenAI and Anthropic, and describe every model being a string swap away. Check the model overview in the documentation for the full list.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Pydantic AI suits Python developers who want LLM output checked against typed models and who may need to switch providers. It is a poor fit for non-programmers wanting a ready-made chat app, for teams that cannot take on a large framework, or for anyone not working in Python.
Install options & downloads