From 8bbaa02c9058d11f3091a90046f692b9f3f391b4 Mon Sep 17 00:00:00 2001 From: laiscarvalho Date: Wed, 12 Nov 2025 12:15:43 +0000 Subject: [PATCH 01/12] consolidate docs in `overview.md` & update mkdocs --- docs/ai_gateway/overview.md | 161 ++++++++++++++++++++++++++++++++++++ mkdocs.yml | 3 + 2 files changed, 164 insertions(+) create mode 100644 docs/ai_gateway/overview.md diff --git a/docs/ai_gateway/overview.md b/docs/ai_gateway/overview.md new file mode 100644 index 0000000000..c965d16db3 --- /dev/null +++ b/docs/ai_gateway/overview.md @@ -0,0 +1,161 @@ +# Pydantic AI Gateway + +**Pydantic AI Gateway** (PAIG) is a unified interface for accessing multiple AI providers with a single key. Features include built-in OpenTelemetry observability, real-time cost monitoring, failover management , and native integration with the Pydantic stack. + +!!! note "Free while in Beta" + The Pydantic AI Gateway is currently in Beta. You can bring your own key (BYOK) or buy inference through the Gateway (we will eat the card fee for now). + +Sign up at [gateway.pydantic.dev](https://gateway.pydantic.dev/). + +For questions and feedback, contact us on [Slack](https://logfire.pydantic.dev/docs/join-slack/). + +## Documentation Integration + +To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), most code examples throughout the Pydantic AI docs include a "Pydantic AI Gateway" tab alongside the standard "Pydantic AI" tab. This allows you to see how to adapt examples for Gateway usage by simply switching tabs. + +The main difference is that when using Gateway, model strings use the `gateway/` prefix. + +## Key features +- **API key management**: access multiple LLM providers with a single Gateway key. +- **Cost Limits**: set spending limits at project, user, and API key levels with daily, weekly, and monthly caps. +- **BYOK and managed providers:** Bring your own API keys (BYOK) from LLM providers, or pay for API usage directly through the platform (_coming soon_). +- **Multi-provider support:** Access models from OpenAI, Anthropic, Google Vertex, Groq, and AWS Bedrock. _More providers coming soon_. +- **Backend observability:** Log every request through [Pydantic Logfire](https://pydantic.dev/logfire) or any OpenTelemetry backend (_coming soon_). +- **Zero translation**: Unlike traditional AI gateways that translate everything to one common schema, PAIG allows requests to flow through directly in each provider's native format. This gives you immediate access to the new model features as soon as they are released. +- **Open source with self-hosting**: PAIG's core is [open source](https://github.com/pydantic/pydantic-ai-gateway/) (under [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html)), allowing self-hosting with file-based configuration, instead of using the managed service. +- **Enterprise ready**: Includes SSO (with OIDC support), granular permissions, and flexible deployment options. Deploy to your Cloudflare account, or run on-premises with our [consulting support](https://pydantic.dev/contact). + +```python {title="hello_word.py"} +from pydantic_ai import Agent + +agent = Agent('gateway/chat:gpt-4.1') + +result = agent.run_sync('Where does "hello world" come from?') +print(result.output) +""" +The first known use of "hello, world" was in a 1974 textbook about the C programming language. +""" +``` +# Quick Start +This section contains instructions on how to set up your account and run your app with Pydantic AI Gateway credentials. + +## Create an account +Using your GitHub or Google account, sign in at https://gateway.pydantic.dev. +Choose a name for your organization (or accept the default). You will automatically be assigned the Admin role. + +A default project will be created for you. You can choose to use it, or create a new one on the [Projects](https://gateway.pydantic.dev/admin/projects) page. + +## Add **Providers** by bringing your own API keys (BYOK) +Pydantic AI Gateway allows you to bring your API keys from your favourite provider(s). + +On the [Providers](https://gateway.pydantic.dev/admin/providers) page, fill in the form to add a provider. Paste your API key into the form under Credentials, and make sure to **select the Project that will be associated to this provider**. It is possible to add multiple keys from the same provider. + +## Grant access to your team +On the [Users](https://gateway.pydantic.dev/admin/users) page, create an invitation and share the URL with your team to allow them to access the project. + +## Create gateway project keys +On the Keys page, Admins can create project keys which are not affected by spending limits. Users can only create personal keys, that will inherit spending caps from both User and Project levels, whichever is more restrictive. + +# Usage +After setting up your account with the instructions above, you will be able to make an AI model request with the Pydantic AI Gateway. +The code snippets below show how you can use PAIG with different frameworks and SDKs. + +To use different models, change the model string `gateway/:` to other models offered by the supported providers. + +Examples of providers and models that can be used are: + +| **Provider** | **Provider ID** | **Example Model** | +| --- | --- | --- | +| OpenAI | `openai` | `gateway/openai:gpt-4.1` | +| Anthropic | `anthropic` | `gateway/anthropic:claude-sonnet-4-5` | +| Google Vertex | `google-vertex` | `gateway/google-vertex:gemini-2.5-flash` | +| Groq | `groq` | `gateway/groq:openai/gpt-oss-120b` | +| AWS Bedrock | `bedrock` | `gateway/bedrock:amazon.nova-micro-v1:0` | + +## Pydantic AI +Before you start, update to the latest version of `pydantic-ai`: + +=== "uv" + + ```bash + uv sync -P pydantic-ai + ``` + +=== "pip" + + ```bash + pip install -U pydantic-ai + ``` + +Set the `PYDANTIC_AI_GATEWAY_API_KEY` environment variable to your gateway API key: + +```bash +export PYDANTIC_AI_GATEWAY_API_KEY="YOUR_PAIG_TOKEN" +``` + +You can access multiple models with the same API key, as shown in the code snippet below. + +```python title="hello_world.py" +from pydantic_ai import Agent + +agent = Agent('gateway/chat:gpt-5') + +result = agent.run_sync('Where does "hello world" come from?') +print(result.output) +""" +The first known use of "hello, world" was in a 1974 textbook about the C programming language. +""" +``` + + +## Claude Code +Before you start, log out of Claude Code using `/logout`. + +Set your gateway credentials as environment variables: + +```bash +export ANTHROPIC_BASE_URL="https://gateway.pydantic.dev/proxy/anthropic" +export ANTHROPIC_AUTH_TOKEN="YOUR_PAIG_TOKEN" +``` + +Replace `YOUR_PAIG_TOKEN` with the API key from the Keys page. + +Launch Claude Code by typing `claude`. All requests will now route through the Pydantic AI Gateway. + +## SDKs + +=== "OpenAI SDK" + + ```python {title="openai_sdk.py" test="skip"} + import openai + + client = openai.Client( + base_url='https://gateway.pydantic.dev/proxy/chat/', + api_key='paig_...', + ) + + response = client.chat.completions.create( + model='gpt-4o', + messages=[{'role': 'user', 'content': 'Hello world'}], + ) + print(response.choices[0].message.content) + #> Hello user + ``` +=== "Anthropic SDK" + + ```python {title="anthropic_sdk.py" test="skip"} + import anthropic + + client = anthropic.Anthropic( + base_url='https://gateway.pydantic.dev/proxy/anthropic/', + auth_token='paig_...', + ) + + response = client.messages.create( + max_tokens=1000, + model='claude-3-haiku-20240307', + messages=[{'role': 'user', 'content': 'Hello world'}], + ) + print(response.content[0].text) + #> Hello user + ``` diff --git a/mkdocs.yml b/mkdocs.yml index 5dbcc0e098..48374e8b4a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,9 @@ nav: - Multi-Agent Patterns: multi-agent-applications.md - Testing: testing.md + - Pydantic AI Gateway: + - Overview: ai_gateway/overview.md + - Pydantic Evals: - Overview: evals.md - Getting Started: From 0fddd50dd2383dbc19de4818d823a445924df084 Mon Sep 17 00:00:00 2001 From: laiscarvalho Date: Wed, 12 Nov 2025 13:16:34 +0000 Subject: [PATCH 02/12] fix typo --- docs/ai_gateway/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ai_gateway/overview.md b/docs/ai_gateway/overview.md index c965d16db3..6b3e99f128 100644 --- a/docs/ai_gateway/overview.md +++ b/docs/ai_gateway/overview.md @@ -25,7 +25,7 @@ The main difference is that when using Gateway, model strings use the `gateway/` - **Open source with self-hosting**: PAIG's core is [open source](https://github.com/pydantic/pydantic-ai-gateway/) (under [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html)), allowing self-hosting with file-based configuration, instead of using the managed service. - **Enterprise ready**: Includes SSO (with OIDC support), granular permissions, and flexible deployment options. Deploy to your Cloudflare account, or run on-premises with our [consulting support](https://pydantic.dev/contact). -```python {title="hello_word.py"} +```python {title="hello_world.py"} from pydantic_ai import Agent agent = Agent('gateway/chat:gpt-4.1') From 483152471884fb28946fc369ebd976a27d590d20 Mon Sep 17 00:00:00 2001 From: laiscarvalho Date: Wed, 12 Nov 2025 13:22:09 +0000 Subject: [PATCH 03/12] skip test --- docs/ai_gateway/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ai_gateway/overview.md b/docs/ai_gateway/overview.md index 6b3e99f128..3c0b465c22 100644 --- a/docs/ai_gateway/overview.md +++ b/docs/ai_gateway/overview.md @@ -25,7 +25,7 @@ The main difference is that when using Gateway, model strings use the `gateway/` - **Open source with self-hosting**: PAIG's core is [open source](https://github.com/pydantic/pydantic-ai-gateway/) (under [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html)), allowing self-hosting with file-based configuration, instead of using the managed service. - **Enterprise ready**: Includes SSO (with OIDC support), granular permissions, and flexible deployment options. Deploy to your Cloudflare account, or run on-premises with our [consulting support](https://pydantic.dev/contact). -```python {title="hello_world.py"} +```python {title="hello_world.py" test="skip"} from pydantic_ai import Agent agent = Agent('gateway/chat:gpt-4.1') @@ -95,7 +95,7 @@ export PYDANTIC_AI_GATEWAY_API_KEY="YOUR_PAIG_TOKEN" You can access multiple models with the same API key, as shown in the code snippet below. -```python title="hello_world.py" +```python {title="hello_world.py" test="skip"} from pydantic_ai import Agent agent = Agent('gateway/chat:gpt-5') From 6111e9c914558a82e38470522f605ca2068598bd Mon Sep 17 00:00:00 2001 From: laiscarvalho Date: Wed, 12 Nov 2025 17:14:39 +0000 Subject: [PATCH 04/12] apply suggested changes --- docs/ai_gateway/{overview.md => gateway.md} | 24 ++++++++++----------- mkdocs.yml | 10 ++++----- 2 files changed, 17 insertions(+), 17 deletions(-) rename docs/ai_gateway/{overview.md => gateway.md} (88%) diff --git a/docs/ai_gateway/overview.md b/docs/ai_gateway/gateway.md similarity index 88% rename from docs/ai_gateway/overview.md rename to docs/ai_gateway/gateway.md index 3c0b465c22..6e2c41162f 100644 --- a/docs/ai_gateway/overview.md +++ b/docs/ai_gateway/gateway.md @@ -11,7 +11,7 @@ For questions and feedback, contact us on [Slack](https://logfire.pydantic.dev/d ## Documentation Integration -To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), most code examples throughout the Pydantic AI docs include a "Pydantic AI Gateway" tab alongside the standard "Pydantic AI" tab. This allows you to see how to adapt examples for Gateway usage by simply switching tabs. +To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), most code examples throughout the Pydantic AI docs include a "Pydantic AI Gateway" tab alongside the standard Pydantic AI call string named here "Direct to Provider API" tab. This allows you to see how to adapt examples for Gateway usage by simply switching tabs. The main difference is that when using Gateway, model strings use the `gateway/` prefix. @@ -64,13 +64,13 @@ To use different models, change the model string `gateway/: Date: Wed, 12 Nov 2025 19:31:16 +0000 Subject: [PATCH 05/12] apply suggested changes --- docs/ai_gateway/gateway.md | 12 +++++------- mkdocs.yml | 8 ++++---- tests/test_examples.py | 1 + 3 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/ai_gateway/gateway.md b/docs/ai_gateway/gateway.md index 6e2c41162f..ded2dc9a28 100644 --- a/docs/ai_gateway/gateway.md +++ b/docs/ai_gateway/gateway.md @@ -1,6 +1,6 @@ # Pydantic AI Gateway -**Pydantic AI Gateway** (PAIG) is a unified interface for accessing multiple AI providers with a single key. Features include built-in OpenTelemetry observability, real-time cost monitoring, failover management , and native integration with the Pydantic stack. +**Pydantic AI Gateway** (PAIG) is a unified interface for accessing multiple AI providers with a single key. Features include built-in OpenTelemetry observability, real-time cost monitoring, failover management, and native integration with the Pydantic stack. !!! note "Free while in Beta" The Pydantic AI Gateway is currently in Beta. You can bring your own key (BYOK) or buy inference through the Gateway (we will eat the card fee for now). @@ -11,24 +11,22 @@ For questions and feedback, contact us on [Slack](https://logfire.pydantic.dev/d ## Documentation Integration -To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), most code examples throughout the Pydantic AI docs include a "Pydantic AI Gateway" tab alongside the standard Pydantic AI call string named here "Direct to Provider API" tab. This allows you to see how to adapt examples for Gateway usage by simply switching tabs. - -The main difference is that when using Gateway, model strings use the `gateway/` prefix. +To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), some code examples on the Pydantic AI documentation include a "Via Pydantic AI Gateway" tab, alongside a "Direct to Provider API" tab with the standard Pydantic AI model string. The main difference between them is that when using Gateway, model strings use the `gateway/` prefix. ## Key features - **API key management**: access multiple LLM providers with a single Gateway key. - **Cost Limits**: set spending limits at project, user, and API key levels with daily, weekly, and monthly caps. -- **BYOK and managed providers:** Bring your own API keys (BYOK) from LLM providers, or pay for API usage directly through the platform (_coming soon_). +- **BYOK and managed providers:** Bring your own API keys (BYOK) from LLM providers, or pay for inference directly through the platform. - **Multi-provider support:** Access models from OpenAI, Anthropic, Google Vertex, Groq, and AWS Bedrock. _More providers coming soon_. - **Backend observability:** Log every request through [Pydantic Logfire](https://pydantic.dev/logfire) or any OpenTelemetry backend (_coming soon_). - **Zero translation**: Unlike traditional AI gateways that translate everything to one common schema, PAIG allows requests to flow through directly in each provider's native format. This gives you immediate access to the new model features as soon as they are released. - **Open source with self-hosting**: PAIG's core is [open source](https://github.com/pydantic/pydantic-ai-gateway/) (under [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html)), allowing self-hosting with file-based configuration, instead of using the managed service. - **Enterprise ready**: Includes SSO (with OIDC support), granular permissions, and flexible deployment options. Deploy to your Cloudflare account, or run on-premises with our [consulting support](https://pydantic.dev/contact). -```python {title="hello_world.py" test="skip"} +```python {title="hello_world.py"} from pydantic_ai import Agent -agent = Agent('gateway/chat:gpt-4.1') +agent = Agent('gateway/chat:gpt-5') result = agent.run_sync('Where does "hello world" come from?') print(result.output) diff --git a/mkdocs.yml b/mkdocs.yml index 0c1311634b..15fe578a49 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,7 +24,7 @@ nav: - message-history.md - direct.md - Models & Providers: - - Overview: models/gateway.md + - Overview: models/overview.md - models/openai.md - models/anthropic.md - models/google.md @@ -63,7 +63,7 @@ nav: - Quick Start: evals/quick-start.md - Core Concepts: evals/core-concepts.md - Evaluators: - - Overview: evals/evaluators/gateway.md + - Overview: evals/evaluators/overview.md - Built-in Evaluators: evals/evaluators/built-in.md - LLM Judge: evals/evaluators/llm-judge.md - Custom Evaluators: evals/evaluators/custom.md @@ -90,12 +90,12 @@ nav: - Integrations: - Debugging & Monitoring with Pydantic Logfire: logfire.md - Durable Execution: - - Overview: durable_execution/gateway.md + - Overview: durable_execution/overview.md - Temporal: durable_execution/temporal.md - DBOS: durable_execution/dbos.md - Prefect: durable_execution/prefect.md - UI Event Streams: - - Overview: ui/gateway.md + - Overview: ui/overview.md - AG-UI: ui/ag-ui.md - Vercel AI: ui/vercel-ai.md - Agent2Agent (A2A): a2a.md diff --git a/tests/test_examples.py b/tests/test_examples.py index cc0ae7b593..85bae688d0 100644 --- a/tests/test_examples.py +++ b/tests/test_examples.py @@ -179,6 +179,7 @@ def print(self, *args: Any, **kwargs: Any) -> None: env.set('MOONSHOTAI_API_KEY', 'testing') env.set('DEEPSEEK_API_KEY', 'testing') env.set('OVHCLOUD_API_KEY', 'testing') + env.set('PYDANTIC_AI_GATEWAY_API_KEY', 'testing') prefix_settings = example.prefix_settings() opt_test = prefix_settings.get('test', '') From 66318897c5ff7ef590d2a5ef493e5e5dcc2eb4a5 Mon Sep 17 00:00:00 2001 From: laiscarvalho Date: Wed, 12 Nov 2025 19:31:43 +0000 Subject: [PATCH 06/12] apply suggested changes --- docs/ai_gateway/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ai_gateway/gateway.md b/docs/ai_gateway/gateway.md index ded2dc9a28..8cdc484f78 100644 --- a/docs/ai_gateway/gateway.md +++ b/docs/ai_gateway/gateway.md @@ -11,7 +11,7 @@ For questions and feedback, contact us on [Slack](https://logfire.pydantic.dev/d ## Documentation Integration -To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), some code examples on the Pydantic AI documentation include a "Via Pydantic AI Gateway" tab, alongside a "Direct to Provider API" tab with the standard Pydantic AI model string. The main difference between them is that when using Gateway, model strings use the `gateway/` prefix. +To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), some code examples on the Pydantic AI documentation include a "Via Pydantic AI Gateway" tab, alongside a "Direct to Provider API" tab with the standard Pydantic AI model string. The main difference between them is that when using Gateway, model strings use the `gateway/` prefix. ## Key features - **API key management**: access multiple LLM providers with a single Gateway key. From d9ce7a94a9fff7f06f5a0422c74507707b8259a7 Mon Sep 17 00:00:00 2001 From: Lais Carvalho Date: Thu, 13 Nov 2025 14:38:41 +0000 Subject: [PATCH 07/12] Update docs/ai_gateway/gateway.md Co-authored-by: Marcelo Trylesinski --- docs/ai_gateway/gateway.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/ai_gateway/gateway.md b/docs/ai_gateway/gateway.md index 8cdc484f78..0d7df83367 100644 --- a/docs/ai_gateway/gateway.md +++ b/docs/ai_gateway/gateway.md @@ -7,7 +7,8 @@ Sign up at [gateway.pydantic.dev](https://gateway.pydantic.dev/). -For questions and feedback, contact us on [Slack](https://logfire.pydantic.dev/docs/join-slack/). +!!! question + For questions and feedback, contact us on [Slack](https://logfire.pydantic.dev/docs/join-slack/). ## Documentation Integration From dca41ed3b91f01149c181d1c73cc3e6cae15c6f5 Mon Sep 17 00:00:00 2001 From: Samuel Colvin Date: Thu, 13 Nov 2025 08:29:24 -0800 Subject: [PATCH 08/12] status icon --- docs/{ai_gateway => }/gateway.md | 5 +++++ mkdocs.yml | 18 ++++++++---------- 2 files changed, 13 insertions(+), 10 deletions(-) rename docs/{ai_gateway => }/gateway.md (99%) diff --git a/docs/ai_gateway/gateway.md b/docs/gateway.md similarity index 99% rename from docs/ai_gateway/gateway.md rename to docs/gateway.md index 0d7df83367..70a2536bb4 100644 --- a/docs/ai_gateway/gateway.md +++ b/docs/gateway.md @@ -1,3 +1,8 @@ +--- +title: Pydantic AI Gateway +status: new +--- + # Pydantic AI Gateway **Pydantic AI Gateway** (PAIG) is a unified interface for accessing multiple AI providers with a single key. Features include built-in OpenTelemetry observability, real-time cost monitoring, failover management, and native integration with the Pydantic stack. diff --git a/mkdocs.yml b/mkdocs.yml index 15fe578a49..14978f8dfa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,7 @@ nav: - install.md - help.md - troubleshooting.md + - Pydantic AI Gateway: gateway.md - Documentation: - Core Concepts: @@ -54,9 +55,6 @@ nav: - Multi-Agent Patterns: multi-agent-applications.md - Testing: testing.md - - Pydantic AI Gateway: - - Overview: ai_gateway/gateway.md - - Pydantic Evals: - Overview: evals.md - Getting Started: @@ -90,14 +88,14 @@ nav: - Integrations: - Debugging & Monitoring with Pydantic Logfire: logfire.md - Durable Execution: - - Overview: durable_execution/overview.md - - Temporal: durable_execution/temporal.md - - DBOS: durable_execution/dbos.md - - Prefect: durable_execution/prefect.md + - Overview: durable_execution/overview.md + - Temporal: durable_execution/temporal.md + - DBOS: durable_execution/dbos.md + - Prefect: durable_execution/prefect.md - UI Event Streams: - - Overview: ui/overview.md - - AG-UI: ui/ag-ui.md - - Vercel AI: ui/vercel-ai.md + - Overview: ui/overview.md + - AG-UI: ui/ag-ui.md + - Vercel AI: ui/vercel-ai.md - Agent2Agent (A2A): a2a.md - Related Packages: From b03d1466d9af10c0550e4211ead5094ae5eb6400 Mon Sep 17 00:00:00 2001 From: laiscarvalho Date: Thu, 13 Nov 2025 17:00:36 +0000 Subject: [PATCH 09/12] apply changes --- docs/gateway.md | 94 +++++++++++++++++++++++++++---------------------- 1 file changed, 52 insertions(+), 42 deletions(-) diff --git a/docs/gateway.md b/docs/gateway.md index 70a2536bb4..8927e87d4c 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -5,7 +5,7 @@ status: new # Pydantic AI Gateway -**Pydantic AI Gateway** (PAIG) is a unified interface for accessing multiple AI providers with a single key. Features include built-in OpenTelemetry observability, real-time cost monitoring, failover management, and native integration with the Pydantic stack. +**[Pydantic AI Gateway](https://pydantic.dev/gateway)** (PAIG) is a unified interface for accessing multiple AI providers with a single key. Features include built-in OpenTelemetry observability, real-time cost monitoring, failover management, and native integration with the other tools in the [Pydantic stack](https://pydantic.dev/). !!! note "Free while in Beta" The Pydantic AI Gateway is currently in Beta. You can bring your own key (BYOK) or buy inference through the Gateway (we will eat the card fee for now). @@ -20,6 +20,7 @@ Sign up at [gateway.pydantic.dev](https://gateway.pydantic.dev/). To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), some code examples on the Pydantic AI documentation include a "Via Pydantic AI Gateway" tab, alongside a "Direct to Provider API" tab with the standard Pydantic AI model string. The main difference between them is that when using Gateway, model strings use the `gateway/` prefix. ## Key features + - **API key management**: access multiple LLM providers with a single Gateway key. - **Cost Limits**: set spending limits at project, user, and API key levels with daily, weekly, and monthly caps. - **BYOK and managed providers:** Bring your own API keys (BYOK) from LLM providers, or pay for inference directly through the platform. @@ -32,7 +33,7 @@ To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev) ```python {title="hello_world.py"} from pydantic_ai import Agent -agent = Agent('gateway/chat:gpt-5') +agent = Agent('gateway/openai:gpt-5') result = agent.run_sync('Where does "hello world" come from?') print(result.output) @@ -41,34 +42,42 @@ The first known use of "hello, world" was in a 1974 textbook about the C program """ ``` # Quick Start + This section contains instructions on how to set up your account and run your app with Pydantic AI Gateway credentials. ## Create an account -Using your GitHub or Google account, sign in at https://gateway.pydantic.dev. + +Using your GitHub or Google account, sign in at [gateway.pydantic.dev](https://gateway.pydantic.dev). Choose a name for your organization (or accept the default). You will automatically be assigned the Admin role. A default project will be created for you. You can choose to use it, or create a new one on the [Projects](https://gateway.pydantic.dev/admin/projects) page. -## Add **Providers** by bringing your own API keys (BYOK) -Pydantic AI Gateway allows you to bring your API keys from your favourite provider(s). +## Add **Providers** +There are two ways to use Providers in the Pydantic AI Gateway: you can bring your own key (BYOK) or buy inference through the platform. + +### Bringing your own API key (BYOK) On the [Providers](https://gateway.pydantic.dev/admin/providers) page, fill in the form to add a provider. Paste your API key into the form under Credentials, and make sure to **select the Project that will be associated to this provider**. It is possible to add multiple keys from the same provider. +### Use Built-in Providers +On the top of the dashboard page, click in the 'Add billing details' button, and put in your credit card details to enable the built-in providers. This will allow you to buy inference through the available providers. + ## Grant access to your team On the [Users](https://gateway.pydantic.dev/admin/users) page, create an invitation and share the URL with your team to allow them to access the project. -## Create gateway project keys +## Create Gateway project keys On the Keys page, Admins can create project keys which are not affected by spending limits. Users can only create personal keys, that will inherit spending caps from both User and Project levels, whichever is more restrictive. # Usage After setting up your account with the instructions above, you will be able to make an AI model request with the Pydantic AI Gateway. The code snippets below show how you can use PAIG with different frameworks and SDKs. +You can add `gateway/` as prefix on every known provider that -To use different models, change the model string `gateway/:` to other models offered by the supported providers. +To use different models, change the model string `gateway/:` to other models offered by the supported providers. Examples of providers and models that can be used are: -| **Provider** | **API Type** | **Example Model** | +| **Provider** | **API Format** | **Example Model** | | --- |-----------------|------------------------------------------| | OpenAI | `openai` | `gateway/openai:gpt-5` | | Anthropic | `anthropic` | `gateway/anthropic:claude-sonnet-4-5` | @@ -77,7 +86,7 @@ Examples of providers and models that can be used are: | AWS Bedrock | `bedrock` | `gateway/bedrock:amazon.nova-micro-v1:0` | ## Pydantic AI -Before you start, update to the latest version of `pydantic-ai`: +Before you start, make sure you are on version 1.16 or later of `pydantic-ai`. To update to the latest version run: === "uv" @@ -91,7 +100,7 @@ Before you start, update to the latest version of `pydantic-ai`: pip install -U pydantic-ai ``` -Set the `PYDANTIC_AI_GATEWAY_API_KEY` environment variable to your gateway API key: +Set the `PYDANTIC_AI_GATEWAY_API_KEY` environment variable to your Gateway API key: ```bash export PYDANTIC_AI_GATEWAY_API_KEY="YOUR_PAIG_TOKEN" @@ -128,38 +137,39 @@ Launch Claude Code by typing `claude`. All requests will now route through the P ## SDKs -=== "OpenAI SDK" +### OpenAI SDK - ```python {title="openai_sdk.py" test="skip"} - import openai +```python {title="openai_sdk.py" test="skip"} +import openai - client = openai.Client( - base_url='https://gateway.pydantic.dev/proxy/chat/', - api_key='paig_...', - ) +client = openai.Client( + base_url='https://gateway.pydantic.dev/proxy/chat/', + api_key='paig_...', +) - response = client.chat.completions.create( - model='gpt-5', - messages=[{'role': 'user', 'content': 'Hello world'}], - ) - print(response.choices[0].message.content) - #> Hello user - ``` -=== "Anthropic SDK" - - ```python {title="anthropic_sdk.py" test="skip"} - import anthropic - - client = anthropic.Anthropic( - base_url='https://gateway.pydantic.dev/proxy/anthropic/', - auth_token='paig_...', - ) - - response = client.messages.create( - max_tokens=1000, - model='claude-sonnet-4-5', - messages=[{'role': 'user', 'content': 'Hello world'}], - ) - print(response.content[0].text) - #> Hello user - ``` +response = client.chat.completions.create( + model='gpt-5', + messages=[{'role': 'user', 'content': 'Hello world'}], +) +print(response.choices[0].message.content) +#> Hello user +``` + +### Anthropic SDK + +```python {title="anthropic_sdk.py" test="skip"} +import anthropic + +client = anthropic.Anthropic( + base_url='https://gateway.pydantic.dev/proxy/anthropic/', + auth_token='paig_...', +) + +response = client.messages.create( + max_tokens=1000, + model='claude-sonnet-4-5', + messages=[{'role': 'user', 'content': 'Hello world'}], +) +print(response.content[0].text) +#> Hello user +``` From 9ae913ee76695411e5098712571ba637eddde611 Mon Sep 17 00:00:00 2001 From: Douwe Maan Date: Thu, 13 Nov 2025 16:50:18 +0000 Subject: [PATCH 10/12] Add banner --- docs/.overrides/main.html | 8 ++++++++ mkdocs.yml | 1 + 2 files changed, 9 insertions(+) create mode 100644 docs/.overrides/main.html diff --git a/docs/.overrides/main.html b/docs/.overrides/main.html new file mode 100644 index 0000000000..a6854bddb5 --- /dev/null +++ b/docs/.overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block announce %} + + Pydantic AI Gateway is now available! 🚀 + Enterprise-ready AI model routing: One key for all your models with real-time monitoring and budget control that works. + +{% endblock %} diff --git a/mkdocs.yml b/mkdocs.yml index 14978f8dfa..5f827ae71b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -234,6 +234,7 @@ theme: - navigation.sections - navigation.tracking - toc.follow + - announce.dismiss logo: "img/logo-white.svg" favicon: "favicon.ico" From a26d08ee4693caf6d956e53fba69610f05898572 Mon Sep 17 00:00:00 2001 From: Lais Carvalho Date: Thu, 13 Nov 2025 17:27:22 +0000 Subject: [PATCH 11/12] Update docs/gateway.md Co-authored-by: summerscope --- docs/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gateway.md b/docs/gateway.md index 8927e87d4c..d8a3171f92 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -12,7 +12,7 @@ status: new Sign up at [gateway.pydantic.dev](https://gateway.pydantic.dev/). -!!! question +!!! question "Questions?" For questions and feedback, contact us on [Slack](https://logfire.pydantic.dev/docs/join-slack/). ## Documentation Integration From 9683f07ac0bc39aa0a60a5e239ee8aa4096fc222 Mon Sep 17 00:00:00 2001 From: Lais Carvalho Date: Thu, 13 Nov 2025 17:37:41 +0000 Subject: [PATCH 12/12] Update docs/gateway.md Co-authored-by: summerscope --- docs/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gateway.md b/docs/gateway.md index d8a3171f92..b063dff028 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -60,7 +60,7 @@ There are two ways to use Providers in the Pydantic AI Gateway: you can bring yo On the [Providers](https://gateway.pydantic.dev/admin/providers) page, fill in the form to add a provider. Paste your API key into the form under Credentials, and make sure to **select the Project that will be associated to this provider**. It is possible to add multiple keys from the same provider. ### Use Built-in Providers -On the top of the dashboard page, click in the 'Add billing details' button, and put in your credit card details to enable the built-in providers. This will allow you to buy inference through the available providers. +Go to the Billing page, add a payment method, and purchase $15 in credits to activate built-in providers. This gives you single-key access to all available models from OpenAI, Anthropic, Google Vertex, AWS Bedrock, and Groq. ## Grant access to your team On the [Users](https://gateway.pydantic.dev/admin/users) page, create an invitation and share the URL with your team to allow them to access the project.