Install & Compatibility
Where this runs
tested against v2.35.1 · 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
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 1.973s · 92.3MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 7.4s · import 1.774s · 92MB
88MB installed
● package 88MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Agent
✓ from pydantic_ai import Agent
The primary interface for interacting with LLMs and defining agents.
BaseModel
✓ from pydantic import BaseModel
Used for defining structured outputs and data schemas for agents and tools.
RunContext
✓ from pydantic_ai import RunContext
Used for dependency injection within agent tools and dynamic instructions.
This quickstart demonstrates how to create a basic Pydantic AI agent using a Google Gemini model. It initializes an `Agent` with a specified model and instructions, then runs a synchronous prompt to get a concise response. Ensure your `GOOGLE_API_KEY` environment variable is set for model access.
import os
from pydantic_ai import Agent
# Ensure GOOGLE_API_KEY is set in your environment
# Example: export GOOGLE_API_KEY="your-api-key-here"
api_key = os.environ.get('GOOGLE_API_KEY')
if not api_key:
print("Warning: GOOGLE_API_KEY environment variable not set. The example may not run.")
agent = Agent(
"google-gla:gemini-1.5-flash",
instructions="You're a helpful assistant. Reply concisely in one sentence."
)
result = agent.run_sync("What is the capital of France?")
print(result.output)
# Expected output: 'The capital of France is Paris.'
Debug
Known issues
gotchaAPI keys must be provided or set as environment variables (e.g., `GOOGLE_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). Forgetting this will result in a `UserError`.fixSet the appropriate API key as an environment variable before running your application, or pass it directly to the model configuration. Refer to the documentation for model-specific environment variable names.
affects: All versions
gotchaWhen using tools, ensure correct decorator usage with `RunContext`. `@agent.tool_plain` does not support `RunContext` as a parameter. `@agent.tool` requires `RunContext[...]` as its first parameter.fixUse `@agent.tool` if your tool function requires `RunContext` and ensure it is the first parameter. Use `@agent.tool_plain` for simpler tools without context.
affects: All versions
breakingVersion 1.0.0 of the broader `pydantic-ai` project (which `pydantic-ai-slim` is part of) dropped support for Python 3.9. Additionally, many dataclasses were made to require keyword arguments. Version 1.0.1 made a breaking change where `TenacityTransport` and `AsyncTenacityTransport` now require `pydantic_ai.retries.RetryConfig` instead of raw `tenacity.Retrying` objects.fixEnsure your environment uses Python 3.10 or newer. Update dataclass instantiations to use keyword arguments. Refactor retry logic to use `pydantic_ai.retries.RetryConfig` as specified.
affects: Pre-1.0.0 versions when upgrading to 1.0.0+, and pre-1.0.1 when upgrading to 1.0.1+
gotchaMixing `async` and `sync` code, especially in environments like Jupyter Notebooks, can lead to `RuntimeError: This event loop is already running`. While modern Jupyter environments support top-level await, legacy setups or specific integrations might require `nest_asyncio`.fixFor synchronous execution in environments with existing event loops, use `agent.run_sync()`. Alternatively, for `async` calls, import and apply `nest_asyncio.apply()` at the beginning of your script.
affects: All versions
gotchaPydantic AI frequently introduces 'beta features' (indicated by a `beta` module) in minor releases. These features' APIs and behaviors may not be stable and are subject to change without backward compatibility guarantees until they are moved out of beta.fixExercise caution when using beta features. Be prepared for potential API changes in subsequent minor releases. Monitor release notes and documentation for updates on beta feature stability.
affects: All versions for features marked 'beta'
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pydantic_ai'
The `pydantic-ai-slim` package was either not installed, installed in a different Python environment, or the import statement incorrectly uses 'pydantic_ai' instead of 'pydantic_ai_slim' or its submodules.
fixEnsure the package is installed in your active environment using `pip install pydantic-ai-slim` and use the correct import statement, such as `from pydantic_ai_slim import Agent` or `from pydantic_ai import Agent` depending on the package you intend to use.
UserError: API key must be provided or set in the [MODEL]_API_KEY environment variable.
The required API key for the chosen Large Language Model (LLM) (e.g., OpenAI, Anthropic, Gemini) has not been provided as an argument during model initialization or set as an environment variable.
fixSet the API key either directly when initializing the model (e.g., `OpenAIModel(api_key='your_key')`) or by setting the corresponding environment variable (e.g., `export OPENAI_API_KEY='your_key'` in your shell, or in a `.env` file).
RuntimeError: This event loop is already running.
This error commonly occurs in interactive environments like Jupyter notebooks or Google Colab when asynchronous functions, such as `Agent.run()`, are called multiple times without proper event loop management.
fixFor modern Jupyter/IPython (7.0+), `Agent.run()` can often be used directly. For legacy environments or to resolve conflicts, use `nest_asyncio.apply()` at the beginning of your script or session, or use `agent.run_sync()` for synchronous execution.
ERROR: Cannot install logfire and pydantic-ai-slim[...] because these package versions have conflicting dependencies.
A conflict exists between the dependency versions required by `pydantic-ai-slim` and another installed package, often `logfire` or `pydantic-ai` itself, particularly when installing optional dependency groups.
fixTry installing `pydantic-ai-slim` with only the specific optional dependencies you need (e.g., `pip install "pydantic-ai-slim[openai]"`) or ensure all your packages, including `pydantic-ai-slim`, are specified with compatible versions in your `requirements.txt` or `pyproject.toml`.
Invalid JSON payload received. Unknown name "$defs" at 'tools.function_declarations[0].parameters': Cannot find field.
The Pydantic-generated JSON schema used for structured output with LLMs (especially for models like Gemini or OpenAI) contains features (like `$defs` for nested models) that the specific LLM API's schema validation does not support or interpret correctly.
fixSimplify your Pydantic model definitions where possible to avoid complex JSON Schema features that LLM APIs might not fully support. Ensure you are using the correct `response_format` settings or adapters provided by `pydantic-ai-slim` or the underlying LLM client for structured output.
Upgrade
Version history
2.35.1latest on PyPI · released Aug 27, 2026
Audit
Dependencies
logfireoptionalOptional dependency for Pydantic Logfire integration and observability. Not included in `pydantic-ai-slim` by default but can be added with `[logfire]` extra.
pydantic-evalsoptionalOptional dependency for the evaluation framework, typically installed with the `[evals]` extra.
openaioptionalOptional dependency for OpenAI model integration, installed with the `[openai]` extra.
google-genaioptionalOptional dependency for Google Gemini models, installed with the `[google]` extra.
anthropicoptionalOptional dependency for Anthropic models, installed with the `[anthropic]` extra.