Pydantic AI

1.75.0 verified Tue May 12 auth: no python install: stale quickstart: stale

Pydantic AI is a Python agent framework built by the Pydantic team, designed for quickly and confidently building production-grade applications and workflows with Generative AI. It leverages Pydantic for structured output validation, type safety, and dependency injection, offering a model-agnostic approach to interacting with various LLM providers. The library integrates seamlessly with observability platforms like Pydantic Logfire for monitoring and debugging.

pip install pydantic-ai

Common errors

error RuntimeError: This event loop is already running. ↓

cause This error occurs when attempting to run asynchronous `pydantic-ai` agent methods (e.g., `agent.run()`) in environments like Jupyter Notebooks or Google Colab where an asyncio event loop is already active.

fix

For modern Jupyter/IPython (7.0+), you can directly use await agent.run(). For legacy environments or to avoid conflicts, use nest_asyncio and agent.run_sync():

import nest_asyncio
from pydantic_ai import Agent

nest_asyncio.apply()
agent = Agent('openai:gpt-5.2')
result = agent.run_sync('Who let the dogs out?')

error UserError: API key must be provided or set in the [MODEL]_API_KEY environment variable. ↓

cause The configured Large Language Model (LLM) provider (e.g., OpenAI, Anthropic, Google) requires an API key for authentication, but it was not provided as an argument during model initialization or set in the corresponding environment variable (e.g., `OPENAI_API_KEY`).

fix

Set the API key as an environment variable (e.g., export OPENAI_API_KEY='your_key_here') before running your application, or pass it directly when initializing the Agent or model:

from pydantic_ai import Agent

# Option 1: Pass as a keyword argument
agent = Agent('openai:gpt-4', api_key='your_openai_api_key')

# Option 2: Ensure environment variable is set
# os.environ['OPENAI_API_KEY'] = 'your_openai_api_key'
agent = Agent('openai:gpt-4')

error ModuleNotFoundError: No module named 'pydantic_ai' ↓

cause The `pydantic-ai` library has not been installed in your current Python environment, or the Python interpreter being used does not have access to the installed package.

fix

Install the library using pip:

pip install pydantic-ai

Ensure you are using the correct Python environment where the package was installed.

error AttributeError: 'OpenAIModel' object has no attribute 'client' ↓

cause This `AttributeError` often arises when there's a misconfiguration or an outdated version of `pydantic-ai` or its dependencies, leading to the `OpenAIModel` instance not properly initializing its internal client object, especially with custom `base_url` setups or older API versions.

fix

Ensure you are using the latest stable versions of pydantic-ai and the openai library. If using a custom base_url (e.g., for local models like Ollama), verify the URL is correct and the server is running. Sometimes, an explicit client configuration might be required for advanced setups. Upgrading pydantic-ai (pip install --upgrade pydantic-ai) often resolves such issues.

error TypeError: Cannot instantiate typing.Union ↓

cause This `TypeError` typically indicates a compatibility issue between `pydantic-ai`'s internal use of Pydantic and the installed version of `openai` or `pydantic` itself, particularly when handling complex type hints like `typing.Union` in LLM responses or model definitions.

fix

Upgrade both pydantic-ai and the openai library to their latest compatible versions. Also, ensure your pydantic library is up to date, as pydantic-ai relies heavily on it. This error was notably resolved in some cases by updating to Pydantic 2.11.0a2 and above.

Warnings

breaking Pydantic AI V2 is expected in April 2026. While V1 commits to API stability, functionality explicitly marked as deprecated will be removed in V2. Always review the upgrade guide for significant version bumps. ↓

fix Consult the official 'Upgrade Guide' and 'Version Policy' documentation, especially for migrations to V2. Address deprecation warnings as they appear in V1.

gotcha Minor releases may introduce 'beta features' with unstable APIs and behaviors that are not backward-compatible. These are typically in `beta` modules. ↓

fix Avoid using beta features in production environments unless explicitly accepting the risk of breaking changes. Monitor release notes for beta features graduating to stable status.

gotcha The library is under rapid development with frequent minor releases (sometimes daily). This means new features are added often, and while V1 aims for stability, interfaces can evolve quickly in minor ways or introduce new best practices. ↓

fix Keep `pydantic-ai` updated and regularly review release notes and the official documentation for changes, new features, and updated patterns. Follow the project's GitHub releases closely.

gotcha Model specification uses a provider-prefixed string (e.g., `openai:gpt-5.2`, `anthropic:claude-sonnet-4-6`). Incorrectly formatted model strings will result in runtime errors. ↓

fix Refer to the official documentation for the correct model string format for each supported provider and model.

gotcha Dependency injection with `deps_type` on `Agent` and `RunContext` is a core concept. Misunderstanding how dependencies are passed to system prompts, tools, and output validators can lead to unexpected behavior or errors. ↓

fix Thoroughly understand the 'Dependencies' section in the official documentation. Ensure `RunContext` is correctly typed when used in agent components and that dependencies are correctly provided during `agent.run()` calls.

Install compatibility stale last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) logfire - - - -

3.10 alpine (musl) openai - - - -

3.10 alpine (musl) pydantic-ai - - - -

3.10 slim (glibc) logfire - - 4.69s 340M

3.10 slim (glibc) openai - - 4.65s 340M

3.10 slim (glibc) pydantic-ai - - 4.76s 340M

3.10 slim (glibc) pydantic-ai - - 5.20s 347M

3.11 alpine (musl) logfire - - - -

3.11 alpine (musl) openai - - - -

3.11 alpine (musl) pydantic-ai - - - -

3.11 slim (glibc) logfire - - 6.14s 366M

3.11 slim (glibc) openai - - 6.25s 366M

3.11 slim (glibc) pydantic-ai - - 6.24s 366M

3.11 slim (glibc) pydantic-ai - - 7.24s 373M

3.12 alpine (musl) logfire - - - -

3.12 alpine (musl) openai - - - -

3.12 alpine (musl) pydantic-ai - - - -

3.12 slim (glibc) logfire - - 7.32s 353M

3.12 slim (glibc) openai - - 7.62s 353M

3.12 slim (glibc) pydantic-ai - - 7.68s 353M

3.12 slim (glibc) pydantic-ai - - 7.43s 360M

3.13 alpine (musl) logfire - - - -

3.13 alpine (musl) openai - - - -

3.13 alpine (musl) pydantic-ai - - - -

3.13 slim (glibc) logfire - - 7.03s 352M

3.13 slim (glibc) openai - - 7.07s 352M

3.13 slim (glibc) pydantic-ai - - 6.90s 352M

3.13 slim (glibc) pydantic-ai - - 6.72s 359M

3.9 alpine (musl) logfire - - - -

3.9 alpine (musl) openai - - - -

3.9 alpine (musl) pydantic-ai - - - -

3.9 slim (glibc) logfire - - 2.12s 249M

3.9 slim (glibc) openai - - 1.20s 245M

3.9 slim (glibc) pydantic-ai - - 1.24s 245M

3.9 slim (glibc) pydantic-ai - - - -

Imports

Agent
```
from pydantic_ai import Agent
```
The primary interface for creating and managing AI agents.
RunContext
```
from pydantic_ai import RunContext
```
Used for accessing dependencies within agent components (system prompts, tools, output validators).
Thinking
```
from pydantic_ai.capabilities import Thinking
```
An example of importing a built-in capability to extend agent behavior.
BaseModel
wrong
```
from pydantic_ai import BaseModel
```
correct
```
from pydantic import BaseModel
```
Pydantic models for structured outputs should be imported directly from `pydantic`, not `pydantic_ai`.

Quickstart stale last tested: 2026-05-12

This quickstart demonstrates how to create a basic Pydantic AI agent, configure it with a model and instructions, and run it to get a concise response.

import os
from pydantic_ai import Agent

# Set your API key for Anthropic (or other model provider)
# os.environ['ANTHROPIC_API_KEY'] = os.environ.get('ANTHROPIC_API_KEY', '')

# Define a simple agent with instructions and a model
agent = Agent(
    'anthropic:claude-sonnet-4-6', # Example model string, replace with your preferred model and provider
    instructions='Be concise, reply with one sentence.',
)

# Run the agent synchronously
result = agent.run_sync('Where does "hello world" come from?')
print(result.output)