> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Pydantic AI (gateway)

> Set up Pydantic AI with the Respan gateway.

Route Pydantic AI model calls through the Respan gateway to use 1000+ models from different providers. Only your `RESPAN_API_KEY` is needed.

## Setup

#### Install packages

```bash
pip install pydantic-ai python-dotenv
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
# Optional overrides
export RESPAN_BASE_URL="https://api.respan.ai/api"
export RESPAN_MODEL="gpt-4o"
```

No provider API key is needed in the application runtime. The Respan gateway handles provider authentication.

#### Point Pydantic AI to the Respan gateway

**`Python`**

```python Python
import os

from pydantic_ai import Agent

respan_api_key = os.environ["RESPAN_API_KEY"]
respan_base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api").rstrip("/")
gateway_api_key = os.getenv("RESPAN_GATEWAY_API_KEY", respan_api_key)
model = os.getenv("RESPAN_MODEL", "gpt-4o")

os.environ["OPENAI_BASE_URL"] = os.getenv("RESPAN_GATEWAY_BASE_URL", respan_base_url).rstrip("/")
os.environ["OPENAI_API_KEY"] = gateway_api_key

agent = Agent(
    model=f"openai:{model}",
    system_prompt="You are a helpful assistant.",
)

result = agent.run_sync("What is the capital of France?")
print(result.output)
```

> **Note**
>
> Pydantic AI reads OpenAI-compatible settings from OpenAI-shaped environment variables for this provider. The code maps those variables from `RESPAN_API_KEY`; users do not need an OpenAI provider key.

## Anthropic provider

If you use Pydantic AI's Anthropic provider, point it at the Anthropic-compatible Respan gateway route and keep using the Respan key as the runtime secret.

**`Python`**

```python Python
import os

from pydantic_ai import Agent

respan_api_key = os.environ["RESPAN_API_KEY"]
respan_base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api").rstrip("/")
model = os.getenv("ANTHROPIC_MODEL", "claude-sonnet-4-5-20250929")

os.environ["ANTHROPIC_BASE_URL"] = f"{respan_base_url}/anthropic"
os.environ["ANTHROPIC_API_KEY"] = respan_api_key

agent = Agent(
    model=f"anthropic:{model}",
    system_prompt="You are a helpful assistant.",
)
```

## Switch models

Change the model string or `RESPAN_MODEL` value to another gateway model ID. The `openai:` prefix uses the Responses API, which serves OpenAI models only. Use the `openai-chat:` prefix for Claude, Gemini, and other providers so Pydantic AI calls Chat Completions.

```python
agent = Agent(
    model="openai-chat:gemini/gemini-3.5-flash",
    system_prompt="You are a helpful assistant.",
)
```

See the [full model list](https://platform.respan.ai/platform/models).