mention PAIG and PAI code example options

Author: laisbsc

docs/agents.md

@@ -18,6 +18,14 @@ The [`Agent`][pydantic_ai.Agent] class has full API documentation, but conceptua
 
 In typing terms, agents are generic in their dependency and output types, e.g., an agent which required dependencies of type `#!python Foobar` and produced outputs of type `#!python list[str]` would have type `Agent[Foobar, list[str]]`. In practice, you shouldn't need to care about this, it should just mean your IDE can tell you when you have the right type, and if you choose to use [static type checking](#static-type-checking) it should work well with Pydantic AI.
 
+!!! info "Code Examples with Gateway Support"
+    Throughout this documentation, code examples are provided in two variations using tabs:
+
+    - **Pydantic AI Gateway**: Shows how to use examples with the [Pydantic AI Gateway](https://gateway.pydantic.dev/), which provides a unified interface to access multiple LLM models with additional features like failover, budget control, and Logfire observability.
+    - **Pydantic AI**: Shows the direct implementation using Pydantic AI with provider-specific model strings.
+
+    Both approaches are functionally equivalent for basic usage. Choose the Gateway tab if you're using Pydantic AI Gateway, or the Pydantic AI tab for direct provider integration.
+
 Here's a toy example of an agent that simulates a roulette wheel:
 
 === "Pydantic AI Gateway"
@@ -109,6 +117,14 @@ There are five ways to run an agent:
 4. [`agent.run_stream_events()`][pydantic_ai.agent.AbstractAgent.run_stream_events] — a function which returns an async iterable of [`AgentStreamEvent`s][pydantic_ai.messages.AgentStreamEvent] and a [`AgentRunResultEvent`][pydantic_ai.run.AgentRunResultEvent] containing the final run result.
 5. [`agent.iter()`][pydantic_ai.Agent.iter] — a context manager which returns an [`AgentRun`][pydantic_ai.agent.AgentRun], an async iterable over the nodes of the agent's underlying [`Graph`][pydantic_graph.graph.Graph].
 
+!!! note "Model String Formats"
+    Examples in this documentation show two model string formats:
+
+    - **Gateway format**: `gateway/chat:gpt-5` or `gateway/anthropic:claude-sonnet-4-5`
+    - **Direct format**: `openai:gpt-5` or `anthropic:claude-sonnet-4-5`
+
+    Use the Gateway format if you're routing requests through Pydantic AI Gateway.
+
 Here's a simple example demonstrating the first four:
 
 === "Pydantic AI Gateway"

docs/gateway/overview.md

@@ -9,6 +9,12 @@ 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.

docs/index.md

@@ -64,6 +64,14 @@ Realistically though, no list is going to be as convincing as [giving it a try](
 
 ## Hello World Example
 
+!!! tip "Two Ways to Run Examples"
+    All code examples in this documentation support both:
+
+    - **Direct usage** with provider-specific models (e.g., `openai:gpt-5`)
+    - **Gateway usage** via Pydantic AI Gateway (e.g., `gateway/chat:gpt-5`)
+
+    Look for the tabs at the top of code examples to switch between implementations. [Learn more about the Gateway →](gateway/overview.md)
+
 Here's a minimal example of Pydantic AI:
 
 ```python {title="hello_world.py"}

docs/install.md

@@ -11,6 +11,12 @@ pip/uv-add pydantic-ai
 This installs the `pydantic_ai` package, core dependencies, and libraries required to use all the models included in Pydantic AI.
 If you want to install only those dependencies required to use a specific model, you can install the ["slim"](#slim-install) version of Pydantic AI.
 
+### Gateway Integration
+
+If you're using Pydantic AI Gateway, you'll see "Pydantic AI Gateway" tabs in code examples throughout the documentation. These show how to adapt examples to use the Gateway's unified model interface.
+
+See the [Gateway documentation](gateway/usage.md) for setup instructions.
+
 ## Use with Pydantic Logfire
 
 Pydantic AI has an excellent (but completely optional) integration with [Pydantic Logfire](https://pydantic.dev/logfire) to help you view and understand agent runs.