Pydantic AI Slim

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

Pydantic AI Slim is an active Python agent framework that provides a slim package designed to use Pydantic with Large Language Models (LLMs), focusing on reduced dependencies. It enables developers to build type-safe LLM agents and handle structured outputs with minimal boilerplate, leveraging Pydantic's data validation capabilities. The library maintains a rapid release cadence, with version 1.75.0 currently available.

pip install pydantic-ai-slim

Common errors

error ModuleNotFoundError: No module named 'pydantic_ai' ↓

cause 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.

fix

Ensure 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.

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

cause 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.

fix

Set 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).

error RuntimeError: This event loop is already running. ↓

cause 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.

fix

For 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 ERROR: Cannot install logfire and pydantic-ai-slim[...] because these package versions have conflicting dependencies. ↓

cause 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.

fix

Try 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.

error Invalid JSON payload received. Unknown name "$defs" at 'tools.function_declarations[0].parameters': Cannot find field. ↓

cause 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.

fix

Simplify 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.

Warnings

gotcha API 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`. ↓

fix Set 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.

gotcha When 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. ↓

fix Use `@agent.tool` if your tool function requires `RunContext` and ensure it is the first parameter. Use `@agent.tool_plain` for simpler tools without context.

breaking Version 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. ↓

fix Ensure 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.

gotcha Mixing `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`. ↓

fix For 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.

gotcha Pydantic 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. ↓

fix Exercise 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.

Install

pip install "pydantic-ai-slim[google]"

pip install "pydantic-ai-slim[openai,anthropic]"

Install compatibility verified last tested: 2026-05-12 v0.8.1 installed · v1.94.0 latest

python os / libc variant status wheel install import disk mem side effects

3.10 alpine (musl) google wheel - 1.58s 75.9M 28.6M clean

3.10 alpine (musl) google - - 1.73s 73.6M 28.0M -

3.10 alpine (musl) openai,anthropic wheel - 1.61s 78.5M 28.6M clean

3.10 alpine (musl) openai,anthropic - - 1.68s 74.4M 28.0M -

3.10 alpine (musl) pydantic-ai-slim wheel - 1.59s 42.7M 28.5M clean

3.10 alpine (musl) pydantic-ai-slim - - 1.73s 41.9M 27.9M -

3.10 slim (glibc) google wheel 8.5s 1.16s 75M 28.6M clean

3.10 slim (glibc) google - - 1.21s 73M 28.0M -

3.10 slim (glibc) openai,anthropic wheel 8.9s 1.12s 78M 28.6M clean

3.10 slim (glibc) openai,anthropic - - 1.30s 74M 28.0M -

3.10 slim (glibc) pydantic-ai-slim wheel 5.4s 1.17s 42M 28.5M clean

3.10 slim (glibc) pydantic-ai-slim - - 1.14s 42M 27.9M -

3.11 alpine (musl) google wheel - 2.15s 84.5M 31.4M clean

3.11 alpine (musl) google - - 2.40s 82.0M 30.8M -

3.11 alpine (musl) openai,anthropic wheel - 2.18s 85.6M 31.4M clean

3.11 alpine (musl) openai,anthropic - - 2.46s 81.2M 30.8M -

3.11 alpine (musl) pydantic-ai-slim wheel - 2.23s 47.4M 31.4M clean

3.11 alpine (musl) pydantic-ai-slim - - 2.40s 46.6M 30.8M -

3.11 slim (glibc) google wheel 7.6s 1.93s 84M 31.4M clean

3.11 slim (glibc) google - - 1.94s 82M 30.8M -

3.11 slim (glibc) openai,anthropic wheel 7.8s 1.98s 85M 31.4M clean

3.11 slim (glibc) openai,anthropic - - 1.91s 81M 30.8M -

3.11 slim (glibc) pydantic-ai-slim wheel 4.5s 1.87s 47M 31.4M clean

3.11 slim (glibc) pydantic-ai-slim - - 2.02s 46M 30.8M -

3.12 alpine (musl) google wheel - 2.20s 74.9M 31.2M clean

3.12 alpine (musl) google - - 2.33s 72.4M 30.6M -

3.12 alpine (musl) openai,anthropic wheel - 2.15s 76.2M 31.2M clean

3.12 alpine (musl) openai,anthropic - - 2.33s 71.8M 30.6M -

3.12 alpine (musl) pydantic-ai-slim wheel - 2.18s 38.6M 31.2M clean

3.12 alpine (musl) pydantic-ai-slim - - 2.44s 37.7M 30.6M -

3.12 slim (glibc) google wheel 6.3s 2.16s 74M 31.2M clean

3.12 slim (glibc) google - - 2.48s 72M 30.6M -

3.12 slim (glibc) openai,anthropic wheel 6.7s 2.18s 76M 31.2M clean

3.12 slim (glibc) openai,anthropic - - 2.29s 71M 30.6M -

3.12 slim (glibc) pydantic-ai-slim wheel 4.0s 2.16s 38M 31.2M clean

3.12 slim (glibc) pydantic-ai-slim - - 2.33s 37M 30.6M -

3.13 alpine (musl) google wheel - 2.04s 74.6M 31.6M clean

3.13 alpine (musl) google - - 2.18s 72.1M 31.1M -

3.13 alpine (musl) openai,anthropic wheel - 2.16s 75.9M 31.6M clean

3.13 alpine (musl) openai,anthropic - - 2.27s 71.5M 31.1M -

3.13 alpine (musl) pydantic-ai-slim wheel - 2.05s 38.3M 31.6M clean

3.13 alpine (musl) pydantic-ai-slim - - 2.26s 37.3M 31.0M -

3.13 slim (glibc) google wheel 6.5s 2.00s 74M 31.6M clean

3.13 slim (glibc) google - - 2.28s 72M 31.1M -

3.13 slim (glibc) openai,anthropic wheel 6.8s 2.01s 75M 31.6M clean

3.13 slim (glibc) openai,anthropic - - 2.29s 71M 31.0M -

3.13 slim (glibc) pydantic-ai-slim wheel 4.0s 2.00s 38M 31.6M clean

3.13 slim (glibc) pydantic-ai-slim - - 2.17s 37M 31.0M -

3.9 alpine (musl) google wheel - 1.18s 65.9M 25.7M noisy

3.9 alpine (musl) google - - 1.31s 64.8M 25.7M -

3.9 alpine (musl) openai,anthropic wheel - 1.27s 65.1M 25.7M noisy

3.9 alpine (musl) openai,anthropic - - 1.32s 61.8M 25.7M -

3.9 alpine (musl) pydantic-ai-slim wheel - 1.22s 37.9M 25.7M noisy

3.9 alpine (musl) pydantic-ai-slim - - 1.30s 37.9M 25.7M -

3.9 slim (glibc) google wheel 9.2s 1.16s 65M 25.7M noisy

3.9 slim (glibc) google - - 1.21s 64M 25.7M -

3.9 slim (glibc) openai,anthropic wheel 8.2s 1.09s 64M 25.7M noisy

3.9 slim (glibc) openai,anthropic - - 1.18s 61M 25.7M -

3.9 slim (glibc) pydantic-ai-slim wheel 6.4s 1.08s 38M 25.7M noisy

3.9 slim (glibc) pydantic-ai-slim - - 1.19s 38M 25.7M -

Imports

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.

Quickstart last tested: 2026-04-24

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.'