Install & Compatibility
Where this runs
tested against v2.35.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✓ 29.2s
217MB installed
● package 217MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ from pydantic import BaseModel
✗ from pydantic_ai import BaseModel
Pydantic models for structured outputs should be imported directly from `pydantic`, not `pydantic_ai`.
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)
Debug
Known issues
breakingPydantic 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.fixConsult the official 'Upgrade Guide' and 'Version Policy' documentation, especially for migrations to V2. Address deprecation warnings as they appear in V1.
affects: >=1.0.0 (upcoming V2)
gotchaMinor releases may introduce 'beta features' with unstable APIs and behaviors that are not backward-compatible. These are typically in `beta` modules.fixAvoid using beta features in production environments unless explicitly accepting the risk of breaking changes. Monitor release notes for beta features graduating to stable status.
affects: All V1.x.x minor releases
gotchaThe 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.fixKeep `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.
affects: All V1.x.x releases
gotchaModel 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.fixRefer to the official documentation for the correct model string format for each supported provider and model.
affects: All versions
gotchaDependency 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.fixThoroughly 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.
affects: All versions
Errors
Common errors & fixes
RuntimeError: This event loop is already running.
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.
fixFor 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()`:
```python
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?')
``` UserError: API key must be provided or set in the [MODEL]_API_KEY environment variable.
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`).
fixSet 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:
```python
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')
``` ModuleNotFoundError: No module named 'pydantic_ai'
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.
fixInstall the library using pip:
```bash
pip install pydantic-ai
```
Ensure you are using the correct Python environment where the package was installed.
AttributeError: 'OpenAIModel' object has no attribute 'client'
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.
fixEnsure 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.
TypeError: Cannot instantiate typing.Union
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.
fixUpgrade 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.
Upgrade
Version history
2.35.0latest on PyPI · released Aug 26, 2026
Audit
Dependencies
pydanticrequiredCore dependency for data validation, structured outputs, and type safety.
httpxoptionalCommonly used for asynchronous HTTP requests within agents and tools, often passed via dependency injection.