add examples to use the gateway aside from the shorthand

docs/api/providers.md

@@ -2,6 +2,10 @@
 
 ::: pydantic_ai.providers.Provider
 
+## Pydantic AI Gateway Provider
+
+::: pydantic_ai.providers.gateway.gateway_provider
+
 ::: pydantic_ai.providers.google
 
 ::: pydantic_ai.providers.openai

docs/deferred-tools.md

@@ -19,7 +19,7 @@ Note that handling deferred tool calls requires `DeferredToolRequests` to be in
 
 If a tool function always requires approval, you can pass the `requires_approval=True` argument to the [`@agent.tool`][pydantic_ai.Agent.tool] decorator, [`@agent.tool_plain`][pydantic_ai.Agent.tool_plain] decorator, [`Tool`][pydantic_ai.tools.Tool] class, [`FunctionToolset.tool`][pydantic_ai.toolsets.FunctionToolset.tool] decorator, or [`FunctionToolset.add_function()`][pydantic_ai.toolsets.FunctionToolset.add_function] method. Inside the function, you can then assume that the tool call has been approved.
 
-If whether a tool function requires approval depends on the tool call arguments or the agent [run context][pydantic_ai.tools.RunContext] (e.g. [dependencies](dependencies.md) or message history), you can raise the [`ApprovalRequired`][pydantic_ai.exceptions.ApprovalRequired] exception from the tool function. The [`RunContext.tool_call_approved`][pydantic_ai.tools.RunContext.tool_call_approved] property will be `True` if the tool call has already been approved.
+Whether a tool function requires approval depends on the tool call arguments or the agent [run context][pydantic_ai.tools.RunContext] (e.g. [dependencies](dependencies.md) or message history), you can raise the [`ApprovalRequired`][pydantic_ai.exceptions.ApprovalRequired] exception from the tool function. The [`RunContext.tool_call_approved`][pydantic_ai.tools.RunContext.tool_call_approved] property will be `True` if the tool call has already been approved.
 
 To require approval for calls to tools provided by a [toolset](toolsets.md) (like an [MCP server](mcp/client.md)), see the [`ApprovalRequiredToolset` documentation](toolsets.md#requiring-tool-approval).
 
@@ -185,7 +185,7 @@ _(This example is complete, it can be run "as is")_
 When the result of a tool call cannot be generated inside the same agent run in which it was called, the tool is considered to be external.
 Examples of external tools are client-side tools implemented by a web or app frontend, and slow tasks that are passed off to a background worker or external service instead of keeping the agent process running.
 
-If whether a tool call should be executed externally depends on the tool call arguments, the agent [run context][pydantic_ai.tools.RunContext] (e.g. [dependencies](dependencies.md) or message history), or how long the task is expected to take, you can define a tool function and conditionally raise the [`CallDeferred`][pydantic_ai.exceptions.CallDeferred] exception. Before raising the exception, the tool function would typically schedule some background task and pass along the [`RunContext.tool_call_id`][pydantic_ai.tools.RunContext.tool_call_id] so that the result can be matched to the deferred tool call later.
+Whether a tool call should be executed externally depends on the tool call arguments, the agent [run context][pydantic_ai.tools.RunContext] (e.g. [dependencies](dependencies.md) or message history), or how long the task is expected to take, you can define a tool function and conditionally raise the [`CallDeferred`][pydantic_ai.exceptions.CallDeferred] exception. Before raising the exception, the tool function would typically schedule some background task and pass along the [`RunContext.tool_call_id`][pydantic_ai.tools.RunContext.tool_call_id] so that the result can be matched to the deferred tool call later.
 
 If a tool is always executed externally and its definition is provided to your code along with a JSON schema for its arguments, you can use an [`ExternalToolset`](toolsets.md#external-toolset). If the external tools are known up front and you don't have the arguments JSON schema handy, you can also define a tool function with the appropriate signature that does nothing but raise the [`CallDeferred`][pydantic_ai.exceptions.CallDeferred] exception.
 

docs/gateway.md

@@ -111,26 +111,71 @@ Before you start, make sure you are on version 1.16 or later of `pydantic-ai`. T
     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_PYDANTIC_AI_GATEWAY_API_KEY"
+export PYDANTIC_AI_GATEWAY_API_KEY="paig_<example_key>"
 ```
 
 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
+=== "Hello World"
 
-agent = Agent('gateway/openai:gpt-5')
+    ```python {title="hello_world.py"}
+    from pydantic_ai import Agent
 
-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.
-"""
-```
+    agent = Agent('gateway/openai: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.
+    """
+    ```
 
+=== "Passing API Key directly"
+
+    Pass your API key directly using the [gateway_provider](https://ai.pydantic.dev/api/providers/#pydantic-ai-gateway-provider):
+
+    ```python {title="passing_api_key.py"}
+    from pydantic_ai import Agent
+    from pydantic_ai.models.openai import OpenAIChatModel
+    from pydantic_ai.providers.gateway import gateway_provider
+
+    provider = gateway_provider('openai', api_key='paig_<example_key>')
+    model = OpenAIChatModel('gpt-5', provider=provider)
+    agent = Agent(model)
+
+    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.
+    """
+    ```
+
+=== "Using a different upstream provider"
+
+    To use an alternate provider or routing group, you can specify it in the route parameter:
+
+    ```python {title="routing_via_provider.py"}
+    from pydantic_ai import Agent
+    from pydantic_ai.models.openai import OpenAIChatModel
+    from pydantic_ai.providers.gateway import gateway_provider
+
+    provider = gateway_provider(
+        'openai',
+        api_key='paig_<example_key>',
+        route='builtin-openai'
+    )
+    model = OpenAIChatModel('gpt-5', provider=provider)
+    agent = Agent(model)
+
+    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