Pydantic AI
Build composable generative-AI applications in Python with type hints and Pydantic validation.
- Source repo
- pydantic/pydantic-ai
- Stars
- ★ 21k
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 65/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Python backend team building first-line bank support that injects a customer ID and database connection through
SupportDependencies. - Not a fit if
- Users who want a no-code, purely graphical agent builder
- Individuals unwilling to supply model API keys or pay per-use costs
- Source review
- 65/100 · Some gaps
What does this agent do, and when should you use it?
Pydantic AI is a Python generative-AI agent framework from the Pydantic team. Developers configure an Agent with a model, instructions, dependency type, and output type, then run conversations synchronously with run_sync or asynchronously with run. Functions can be registered as model-callable tools, while RunContext passes runtime dependencies into dynamic instructions and tools. Pydantic models can validate outputs, and the framework also documents streamed structured output, graphs, evaluations, durable execution, MCP, and UI event streams. It fits teams that want production-oriented agent workflows expressed through Python types, while model access still depends on the selected provider.
An application creates an Agent, for example with 'anthropic:claude-sonnet-4-6' or 'openai:gpt-5.2', plus instructions, deps_type, and output_type. It then calls agent.run_sync(prompt) or await agent.run(prompt, deps=...); the framework sends instructions and the user prompt to the model and continues through model tool calls until a final result is reached. @agent.instructions can generate instructions dynamically from RunContext[DepsType], and @agent.tool registers functions whose descriptions and parameter schemas are made available to the model. Pydantic validates tool arguments and the declared output_type; the supplied material says validation failures prompt the model to retry. The final value is read from result.output, as text or a declared structured Pydantic output.
- A Python backend team building first-line bank support that injects a customer ID and database connection through
SupportDependencies. - An application team that needs fixed response fields such as advice, risk level, and an action flag, validated through a
BaseModeloutput type. - Developers exposing internal business-data lookups, such as an asynchronous customer-balance function, as
@agent.toolfunctions. - Teams whose prompts must reflect user, session, or business context and can generate dynamic instructions with
@agent.instructionsandRunContext. - Engineering teams assessing graph workflows, durable execution, human approval, and MCP integration for complex or long-running workflows.
How do you install or deploy this agent?
The supplied material states that the pydantic_ai package must be installed and links to an installation page, but it provides no copyable install command, supported Python version, version constraint, or credential setup. An exact installation command therefore cannot be verified from the available material. The examples also require credentials for the chosen model provider, but no environment-variable names or authentication procedure are documented here.
How do you use this agent?
After installing the package and configuring credentials for the selected model provider, follow the supplied pattern: 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?'); then read result.output. For structured responses, pass a Pydantic BaseModel as output_type. For asynchronous dependencies and tools, call await support_agent.run(..., deps=deps) and register functions with @support_agent.tool.
What are this agent's strengths and limitations?
- Its
Agent[Dependencies, Output],RunContext, and Python type-hint pattern explicitly carries dependency and output types through the agent design. - Tool arguments and structured outputs use Pydantic validation, and the material states that invalid output prompts a retry.
- It documents a multi-provider path covering OpenAI, Anthropic, Gemini, DeepSeek, Mistral, Amazon Bedrock, Ollama, LiteLLM, and others, with custom models available.
- Composable capabilities cover thinking, web search, and MCP, and agents can be defined in YAML or JSON according to the material.
- It integrates with Pydantic Logfire and other OpenTelemetry-compatible observability backends for tracing, evaluation, and cost monitoring.
- The supplied material does not specify an install command, Python version, dependency-pinning approach, or credential configuration, leaving first-run setup details unresolved.
- Actual execution depends on the chosen model or provider; feature availability and cost across providers, models, and capabilities are not itemized here.
- Dynamic instructions, tools, and dependency injection require the application to supply its own database connections, business logic, and error handling.
- Although durable execution, approvals, MCP, graphs, and UI event streams are documented as capabilities, the material provides no minimal configuration or complete end-to-end example for them.
- Validation retries can add provider calls and latency when generated output does not satisfy the declared schema.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Pydantic AI This agent | 65 · Some gaps | Library / SDKFree + model costs | ★ 21k | today | Python | OpenAI API · Claude API |
| AgentLoom | 52 · Major gaps | — | ★ 169 | today | Python | OpenAI API |
| Julep — Durable, Composable AI Agents | 64 · Some gaps | Library / SDKFree + model costs | ★ 6.6k | 3mo ago | Python | — |
| Agently AI Application Runtime | 63 · Some gaps | Library / SDKFree + model costs | ★ 1.7k | 24d ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: README explicitly supports human-in-the-loop tool approval, indicating user confirmation mechanism; pyproject.toml includes security-driven dependency floors (e.g., urllib3>=2.7.0, cryptography>=48.0.1), showing dependency security consideration; but no explicit documentation on least privilege, data flow transparency only indirectly via observability integration, sensitive data handling and external effects (e.g., tool side effects) lack detail, rollback not mentioned. Deductions: least privilege, data flow transparency, sensitive data handling, external effects, rollback lack direct evidence.
Evidence: README and pyproject.toml are consistent, framework positioning clear; dependency management uses uv workspace and constraint dependencies, but no dependency availability guarantees (e.g., mirrors or lock files); failure messages: test config shows some attention via filterwarnings and error handling, but no user-facing failure message documentation. Deductions: dependency availability and failure messages lack direct evidence.
Evidence: README clearly targets production-grade developers, scenarios cover tools, structured output, streaming, graphs, etc.; capability boundaries via composable capabilities and custom model interface; trigger precision: tool and instruction registration mechanisms clear; environment fit supports many models and providers, but no explicit deployment environment requirements. Deductions: environment fit lacks specific deployment details.
Evidence: README structure clear, includes docs links, examples, next steps; install notes point to docs but not detailed in repo; naming stable, package name and CLI command clear; examples rich, including Hello World and tool examples; known limitations not explicitly listed; license MIT, clear; versioning via dynamic version and changelog link, but no detailed changelog; maintenance responsibility by Pydantic team, but unverified. Deductions: install notes, known limitations, versioning changelog, maintenance responsibility evidence insufficient.
Evidence: output usability via structured and streamed outputs; marginal value high, offering type safety, observability, evals, etc.; cost-benefit: open source free, but no performance or resource consumption data. Deductions: cost-benefit lacks data support.
Evidence: README claims (e.g., model support, features) traceable to docs and code; cross-source corroboration: README consistent with pyproject.toml, but not cross-verified with independent sources; fact-inference separation: README distinguishes feature descriptions and examples, but inferences not explicitly marked. Deductions: cross-source corroboration and fact-inference separation lack explicit evidence.
- Publisher identity is unverified; treat as unknown, do not infer safety from brand.
- Static review cannot verify actual runtime behavior; all scores based on source and docs, confidence low.
- Dependency security has version floors but no lock files or supply chain verification; verify in deployment.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.107.10 v1.107.10 (2026-11-04)
Release notes excerpt
What's Changed 🛡️ Security * [GHSA-m5vj-8mcw-82qx](https://github.com/pydantic/pydantic-ai/security/advisories/GHSA-m5vj-8mcw-82qx) (high): web_fetch_tool and the WebFetch capability's local fallback re-indented a JSON response on the event loop before applying the returned-content limit, so a deeply nested document within the download size limit could expand to hundreds of times its size, using large amounts of memory and delaying other work in the same process. You are affected if an attacker can choose or influence the URLs the tool fetches. Provider-native web fetching is not af …View on GitHub ↗ -
v2.66.0 v2.66.0 (2026-11-04)
Release notes excerpt
<!-- Release notes generated using configuration in .github/release.yml at 7d1d3f0191fd5d500b02e58dee2bf6d7adc1b967 --> What's Changed 🛡️ Security * [GHSA-m5vj-8mcw-82qx](https://github.com/pydantic/pydantic-ai/security/advisories/GHSA-m5vj-8mcw-82qx) (high): web_fetch_tool and the WebFetch capability's local fallback re-indented a JSON response on the event loop before applying the returned-content limit, so a deeply nested document within the download size limit could expand to hundreds of times its size, using large amounts of memory and delaying other work in the same process. …View on GitHub ↗ -
v2.65.0 v2.65.0 (2026-11-02)
Release notes excerpt
<!-- Release notes generated using configuration in .github/release.yml at a56a6d6f138d1e3a9c45a9697ea513bef47a6cea --> What's Changed ⚠️ Compatibility Notes * Protect the gh-aw canonical session capture from agent tools by @dsfaccini in https://github.com/pydantic/pydantic-ai/pull/10606 * Add multimodal notes to AskUserAnswer by @dsfaccini in https://github.com/pydantic/pydantic-ai/pull/11664 * Count BrowserUse model calls toward the host run's usage and UsageLimits by @mpfaffenberger in https://github.com/pydantic/pydantic-ai/pull/11860 …View on GitHub ↗
FAQ
Is Pydantic AI tied to one model provider?
How are business-shaped model responses enforced?
BaseModel as output_type when creating the Agent. The supplied material says the result is validated and validation failure prompts the model to retry.Can the model call internal application functions?
@agent.tool; their parameters become the tool schema available to the model. RunContext can carry application-provided dependencies.