shishantbiswas/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-06-02 20:48:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify Coder Agents AI Gateway routing (#25852)

Browse Source 
> Mux updated this PR on behalf of Mike.

Clarifies that Coder Agents route through AI Gateway automatically,
while admins configure Agents providers with upstream provider or proxy
endpoint/base URLs.

Moves Agents-specific setup and credential guidance into the Agents
models page, removes the obsolete AI Gateway Coder Agents client page,
removes Coder Agents from the AI Gateway external client list, and links
BYOK credential selection to the global AI Gateway BYOK setting.
This commit is contained in:
Michael Suchacz
2026-06-02 16:59:29 +02:00
committed by GitHub
parent 43e58dcff8
commit efbaedeefb
8 changed files with 143 additions and 360 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai-coder/agents/getting-started.md
+7 -5
View File
@@ -37,11 +37,13 @@ Before you begin, confirm the following:
To configure Coder Agents: To configure Coder Agents:
1. Navigate to the **Agents** page in the Coder dashboard. 1. Navigate to **Admin settings** > **AI** and select **Providers**.
1. Open **Settings** > **Manage Agents** and select the **Providers** tab. 1. Add or update a provider with its credentials and upstream endpoint, then
Pick a provider, enter your API key, and save. save it.
1. Switch to the **Models** tab, click **Add**, and configure at least one 1. Navigate to the **Agents** page, open **Settings** > **Manage Agents**, and
model with its identifier, display name, and context limit. select **Models**.
1. Click **Add** and configure at least one model with its identifier, display
name, and context limit.
1. Click the **star icon** next to a model to set it as the default. 1. Click the **star icon** next to a model to set it as the default.
Detailed instructions for each provider and model option are in the Detailed instructions for each provider and model option are in the
docs/ai-coder/agents/models.md
+93 -113
View File
@@ -1,26 +1,29 @@
# Models # Models
Administrators configure LLM providers and models from the Coder dashboard. Administrators configure LLM providers from **Admin settings** > **AI** and
Providers, models, and centrally managed credentials are deployment-wide Coder Agents models from the **Agents** settings page. Providers, models, and
settings managed by platform teams. Developers select from the set of models centrally managed credentials are deployment-wide settings managed by platform
that an administrator has enabled. teams. Developers select from the set of models that an administrator has
enabled.
Optionally, administrators can allow developers to supply their own API keys Optionally, administrators can enable AI Gateway Bring Your Own Key (BYOK)
for specific providers. See [User API keys](#user-api-keys-byok) below. so developers can supply personal API keys for providers. See
[User API keys](#user-api-keys-byok) below.
## Providers ## Providers
Each LLM provider has a type, a credential configuration, and an optional base URL override. Each LLM provider has a type, credentials, and an endpoint/base URL for the
upstream provider or proxy.
Coder supports the following provider types: Coder supports the following provider types:
| Provider | Description | | Provider | Description |
|-------------------|------------------------------------------------------------------| |-------------------|------------------------------------------|
| Anthropic | Claude models via Anthropic API | | Anthropic | Claude models via Anthropic API |
| OpenAI | GPT and o-series models via OpenAI API | | OpenAI | GPT and o-series models via OpenAI API |
| Google | Gemini models via Google AI API | | Google | Gemini models via Google AI API |
| Azure OpenAI | OpenAI models hosted on Azure | | Azure OpenAI | OpenAI models hosted on Azure |
| AWS Bedrock | Models via AWS Bedrock (bearer token or ambient AWS credentials) | | AWS Bedrock | Models via AWS Bedrock |
| OpenAI Compatible | Any endpoint implementing the OpenAI API | | OpenAI Compatible | Any endpoint implementing the OpenAI API |
| OpenRouter | Multi-model routing via OpenRouter | | OpenRouter | Multi-model routing via OpenRouter |
| Vercel AI Gateway | Models via Vercel AI SDK | | Vercel AI Gateway | Models via Vercel AI SDK |
@@ -29,49 +32,56 @@ The **OpenAI Compatible** type is a catch-all for any service that exposes an
OpenAI-compatible chat completions endpoint. Use it to connect to self-hosted OpenAI-compatible chat completions endpoint. Use it to connect to self-hosted
models, internal gateways, or third-party proxies like LiteLLM. models, internal gateways, or third-party proxies like LiteLLM.
Coder Agents route model requests through AI Gateway automatically by using
the provider configuration stored in Coder's database.
### Add a provider ### Add a provider
1. Navigate to the **Agents** page in the Coder dashboard. LLM providers are managed from the deployment AI settings, not from the Agents
1. Open **Settings** > **Manage Agents** and select the **Providers** tab. settings page.
1. Click the provider you want to configure.
1. Enter the **API key** for the provider, if required. 1. Navigate to **Admin settings** > **AI**.
1. Optionally set a **Base URL** to override the default endpoint. This is 1. Select **Providers**.
useful for enterprise proxies, regional endpoints, or self-hosted models. 1. Click **Add provider**.
1. Select the provider type.
1. Enter a unique lowercase provider name, the credentials, and the upstream
provider or proxy
[endpoint/base URL](#endpointbase-url-for-openai-compatible-providers).
1. Click **Save**. 1. Click **Save**.
<img src="../../images/guides/ai-agents/models-providers.png" alt="Screenshot of the providers list in the Agents settings"> After saving a provider, add an Agents model for it from **Agents** >
**Settings** > **Manage Agents** > **Models**. For provider-specific setup,
including AWS Bedrock, see
[AI Gateway provider configuration](../ai-gateway/providers.md#provider-types).
<small>The providers list shows all supported providers and their configuration ## Endpoint/base URL for OpenAI-compatible providers
status.</small>
<img src="../../images/guides/ai-agents/models-add-provider.png" alt="Screenshot of the add provider form"> Provider configuration stores an absolute HTTP(S) endpoint/base URL. Syntax
validation confirms that the value is a URL, but it does not prove the upstream
implements the APIs Coder sends.
<small>Adding a provider usually requires an API key. AWS Bedrock can also use For the default Agents path through AI Gateway, set the endpoint/base URL to
ambient AWS credentials. The base URL is optional.</small> the upstream provider or proxy endpoint. Do not set it to Coder's public AI
Gateway route, such as `https://<coder-host>/api/v2/aibridge/openai/v1`.
## Configuring AWS Bedrock OpenAI-shaped provider types require the upstream OpenAI-compatible prefix in
the endpoint/base URL because Coder appends request suffixes such as
`/chat/completions`, `/responses`, and `/models`. This applies to **OpenAI**,
**Azure OpenAI**, **Google**, **OpenAI Compatible**, **OpenRouter**, and
**Vercel AI Gateway** provider types.
AWS Bedrock supports two credential modes for Agents providers: Examples:
- **Bearer token mode**: Enter a Bedrock-compatible bearer token in the | Provider type | Example endpoint/base URL |
**API key** field when you add the provider. |-------------------------------------|------------------------------------------------------------|
- **Ambient AWS credentials mode**: Leave the **API key** field empty. The | OpenAI | `https://api.openai.com/v1/` |
Coder server resolves credentials from the standard AWS SDK credential chain, | Azure OpenAI | `https://<resource-name>.openai.azure.com/openai/v1` |
including IAM instance roles and `AWS_ACCESS_KEY_ID` / | Google Gemini OpenAI-compatible API | `https://generativelanguage.googleapis.com/v1beta/openai/` |
`AWS_SECRET_ACCESS_KEY` environment variables. | OpenRouter | `https://openrouter.ai/api/v1` |
| Vercel AI Gateway | `https://ai-gateway.vercel.sh/v1` |
| Generic OpenAI-compatible proxy | `https://provider.example.com/v1` |
Region comes from the standard AWS SDK configuration. In most deployments, set Confirm the exact endpoint/base URL in your provider or proxy documentation.
`AWS_REGION` on the Coder server. Bearer token mode falls back to `us-east-1`
when no region is configured. Ambient credentials require a region from the
standard AWS SDK chain, for example `AWS_REGION`.
The **Base URL** field overrides the Bedrock runtime endpoint. Use it for
custom endpoints or VPC endpoints.
> [!NOTE]
> Agents Bedrock provider configuration is separate from AI Gateway Bedrock
> flags (`CODER_AI_GATEWAY_BEDROCK_*`). AI Gateway and Agents use independent
> credential paths.
## Provider credentials and security ## Provider credentials and security
@@ -80,47 +90,30 @@ database. They are never exposed to workspaces, developers, or the browser
after initial entry. The dashboard shows only whether a key is set, not the after initial entry. The dashboard shows only whether a key is set, not the
key itself. key itself.
When a provider uses ambient credentials, Coder resolves them from the server
environment at request time instead of storing a secret in the database.
Because the agent loop runs in the control plane, workspaces never need direct Because the agent loop runs in the control plane, workspaces never need direct
access to LLM providers. See access to LLM providers. See
[Architecture](./architecture.md#no-api-keys-in-workspaces) for details [Architecture](./architecture.md#no-api-keys-in-workspaces) for details
on this security model. on this security model.
## Key policy ## Credential selection
Each provider has three policy flags that control how provider credentials are Coder Agents use the AI providers configured by administrators. Provider API
sourced: keys entered by administrators are centralized credentials for the deployment.
| Setting | Default | Description | BYOK for Coder Agents is controlled by the
|-------------------------|---------|--------------------------------------------------------------------------------------------------------------------------| [global AI Gateway BYOK setting](../ai-gateway/auth.md#bring-your-own-key-byok),
| Central API key | On | The provider uses deployment-managed credentials configured by an administrator. For most providers, this is an API key. | not by per-provider key policy flags. When BYOK is enabled, users can save a
| Allow user API keys | Off | Developers may supply their own API key for this provider. | personal API key for any enabled AI provider. When BYOK is disabled, saved user
| Central key as fallback | Off | When user keys are allowed, fall back to deployment-managed credentials if a developer has not set a personal key. | keys are ignored and users cannot add or update personal keys.
At least one credential source must be enabled. These settings appear in the For each provider request, Coder selects credentials in this order:
provider configuration form under **Key policy**.
The interaction between these flags determines whether a provider is available 1. If BYOK is enabled and the user has saved a personal key for the selected
to a given developer: provider, Coder uses the user's key.
1. Otherwise, Coder uses centralized provider credentials when they are
| Central key | User keys allowed | Fallback | Developer has key | Result | configured.
|-------------|-------------------|----------|-------------------|----------------------| 1. If neither a usable user key nor centralized credentials are available, the
| On | Off | — | — | Uses central key | provider is unavailable for that user.
| Off | On | — | Yes | Uses developer's key |
| Off | On | — | No | Unavailable |
| On | On | Off | Yes | Uses developer's key |
| On | On | Off | No | Unavailable |
| On | On | On | Yes | Uses developer's key |
| On | On | On | No | Uses central key |
When a developer's personal key is present, it always takes precedence over
deployment-managed credentials. When user keys are required and fallback is
disabled, the provider is unavailable to developers who have not saved a
personal key, even if deployment-managed credentials exist. This is
intentional: it enforces that each developer authenticates with their own
credentials.
## Models ## Models
@@ -131,11 +124,11 @@ generation parameters, and provider-specific options.
1. Open **Settings** > **Manage Agents** and select the **Models** tab. 1. Open **Settings** > **Manage Agents** and select the **Models** tab.
1. Click **Add** and select the provider for the new model. 1. Click **Add** and select the provider for the new model.
1. Enter the **Model Identifier** — the exact model string your provider 1. Enter the **Model Identifier**, the exact model string your provider
expects (e.g., `claude-opus-4-6`, `gpt-5.3-codex`). expects (e.g., `claude-opus-4-6`, `gpt-5.3-codex`).
1. Set a **Display Name** so developers see a human-readable label in the model 1. Set a **Display Name** so developers see a human-readable label in the model
selector. selector.
1. Set the **Context Limit** — the maximum number of tokens in the model's 1. Set the **Context Limit**, the maximum number of tokens in the model's
context window (e.g., `200000` for Claude Sonnet). context window (e.g., `200000` for Claude Sonnet).
1. Configure any provider-specific options (see below). 1. Configure any provider-specific options (see below).
1. Click **Save**. 1. Click **Save**.
@@ -171,7 +164,7 @@ These options apply to all providers:
| Model Identifier | The API model string sent to the provider (e.g., `claude-opus-4-6`). | | Model Identifier | The API model string sent to the provider (e.g., `claude-opus-4-6`). |
| Display Name | The label shown to developers in the model selector. | | Display Name | The label shown to developers in the model selector. |
| Context Limit | Maximum tokens in the context window. Used to determine when context compaction triggers. | | Context Limit | Maximum tokens in the context window. Used to determine when context compaction triggers. |
| Compression Threshold | Percentage (0–100) of context usage at which the agent compresses older messages into a summary. | | Compression Threshold | Percentage (0-100) of context usage at which the agent compresses older messages into a summary. |
| Max Output Tokens | Maximum tokens generated per model response. | | Max Output Tokens | Maximum tokens generated per model response. |
| Temperature | Controls randomness. Lower values produce more deterministic output. | | Temperature | Controls randomness. Lower values produce more deterministic output. |
| Top P | Nucleus sampling threshold. | | Top P | Nucleus sampling threshold. |
@@ -238,9 +231,9 @@ are active.
The model selector uses the following precedence to pre-select a model: The model selector uses the following precedence to pre-select a model:
1. **Last used model** — stored in the browser's local storage. 1. **Last used model**, stored in the browser's local storage.
1. **Admin-designated default** — the model marked with the star icon. 1. **Admin-designated default**, the model marked with the star icon.
1. **First available model** — if no default is set and no history exists. 1. **First available model**, if no default is set and no history exists.
Developers cannot add their own providers or models. If no models are Developers cannot add their own providers or models. If no models are
configured, the chat interface displays a message directing developers to configured, the chat interface displays a message directing developers to
@@ -284,57 +277,44 @@ and resolution falls through to the next.
## User API keys (BYOK) ## User API keys (BYOK)
When an administrator enables **Allow user API keys** on a provider, When [AI Gateway BYOK](../ai-gateway/auth.md#bring-your-own-key-byok) is
developers can supply their own API key from the Agents settings page. enabled, developers can supply personal API keys for any enabled AI provider
from the Agents settings page.
### Managing personal API keys ### Managing personal API keys
1. Navigate to the **Agents** page in the Coder dashboard. 1. Navigate to the **Agents** page in the Coder dashboard.
1. Open **Settings** and select the **API Keys** tab. 1. Open **Settings** and select the **API Keys** tab.
1. Each provider that allows user keys is listed with a status indicator: 1. Each enabled provider is listed with a status indicator:
- **Key saved** — your personal key is active and will be used for requests. - **Key saved**, your personal key is active and will be used for requests to
- **Using shared key** — no personal key set, but the central deployment that provider.
key is available as a fallback. - **Using shared key**, no personal key is set and Coder is using
- **No key** — you must add a personal key before you can use this provider. deployment-managed credentials for that provider.
- **No key**, no personal key or deployment-managed credential is available.
Add a personal key before you use models from this provider.
1. Enter your API key and click **Save**. 1. Enter your API key and click **Save**.
Personal API keys are encrypted at rest using the same database encryption Personal API keys are encrypted at rest using the same database encryption
used for deployment-managed provider secrets. The dashboard never displays a used for deployment-managed provider secrets. The dashboard never displays a
saved key, only whether one is set. saved key, only whether one is set.
### How key selection works
When you start a chat, the control plane resolves which credential source to
use for each provider:
1. If you have a personal key for the provider, it is used.
1. If you do not have a personal key and central key fallback is enabled,
deployment-managed credentials are used.
1. If you do not have a personal key and fallback is disabled, the provider
is unavailable to you. Models from that provider will not appear in the
model selector.
### Removing a personal key ### Removing a personal key
Click **Remove** on the provider card in the API Keys settings tab. If Click **Remove** on the provider card in the API Keys settings tab. Subsequent
central key fallback is enabled, subsequent requests will use the shared requests use deployment-managed credentials when they are configured for that
deployment-managed credentials. If fallback is disabled, the provider becomes provider. If no deployment-managed credential is available, add a new personal
unavailable until you add a new personal key. key before you use models from that provider.
## Using an LLM proxy ## Using an LLM proxy
Organizations that route LLM traffic through a centralized proxy — such as Organizations that route LLM traffic through a centralized proxy, such as
Coder's AI Gateway or third parties like LiteLLM — can point any provider's **Base URL** at their proxy endpoint. LiteLLM or an internal gateway, can point a provider's **Endpoint** or **Base
URL** at that upstream proxy endpoint. Enter the API key your proxy expects.
For example, to route all OpenAI traffic through Coder's AI Gateway: Use the **OpenAI Compatible** provider type if your proxy serves multiple model
families through a single OpenAI-compatible endpoint. Include the proxy
1. Add or edit the **OpenAI** provider. provider's documented OpenAI-compatible path prefix, such as `/v1`, when
1. Set the **Base URL** to your AI Gateway endpoint required.
(e.g., `https://example.coder.com/api/v2/aibridge/openai/v1`).
1. Enter the API key your proxy expects.
Alternatively, use the **OpenAI Compatible** provider type if your proxy serves
multiple model families through a single OpenAI-compatible endpoint.
This lets you keep existing proxy-level features like per-user budgets, rate This lets you keep existing proxy-level features like per-user budgets, rate
limiting, and audit logging while using Coder Agents as the developer interface. limiting, and audit logging while using Coder Agents as the developer interface.
docs/ai-coder/agents/platform-controls/mcp-servers.md
+2 -4
View File
@@ -143,10 +143,8 @@ auth header for the configured `auth_type`:
| `X-Coder-Subchat-Id` | Subchat ID. Only present when the request originates from a child chat. | | `X-Coder-Subchat-Id` | Subchat ID. Only present when the request originates from a child chat. |
| `X-Coder-Workspace-Id` | Workspace associated with the chat, if any. | | `X-Coder-Workspace-Id` | Workspace associated with the chat, if any. |
These are the same headers Coder sends to LLM providers (see Coder sends the same identity headers to LLM providers, so a first-party
[Coder agents headers](../../ai-gateway/clients/coder-agents.md)) so a MCP server can correlate a tool call back to the originating chat.
first-party MCP server can correlate a tool call back to the
originating chat.
Because the headers leak chat identity, the option is **off by Because the headers leak chat identity, the option is **off by
default** and should only be enabled for first-party or trusted default** and should only be enabled for first-party or trusted
docs/ai-coder/agents/tasks-to-chats-migration.md
+5 -4
View File
@@ -68,10 +68,11 @@ With Tasks, LLM credentials are injected into the workspace as environment
variables (e.g. `ANTHROPIC_API_KEY`). With Coder Agents, credentials are variables (e.g. `ANTHROPIC_API_KEY`). With Coder Agents, credentials are
configured once in the control plane: configured once in the control plane:
1. Navigate to the **Agents** page in the Coder dashboard. 1. Navigate to **Admin settings** > **AI** and select **Providers**.
1. Open **Settings** > **Manage Agents** > **Providers**, pick a provider, 1. Add or update a provider with its credentials and upstream endpoint, then
enter your API key, and save. save it.
1. Under **Models**, add at least one model and set it as the default. 1. Navigate to the **Agents** page, open **Settings** > **Manage Agents** >
**Models**, add at least one model, and set it as the default.
You no longer pass API keys in template variables or workspace environment. See https://coder.com/docs/ai-coder/agents/getting-started for more information. You no longer pass API keys in template variables or workspace environment. See https://coder.com/docs/ai-coder/agents/getting-started for more information.
docs/ai-coder/ai-gateway/auth.md
+9 -1
View File
@@ -88,7 +88,7 @@ In BYOK mode, users need two credentials:
BYOK and centralized modes can be used together. BYOK and centralized modes can be used together.
When a user provides their own credential, AI Gateway forwards it directly. When a user provides their own credential, AI Gateway forwards it directly.
When no user credential is present, AI Gateway falls back to the admin-configured provider key. When no user credential is present, AI Gateway uses the admin-configured provider key.
This approach offers centralized keys as a default, This approach offers centralized keys as a default,
while allowing individual users to bring their own key. while allowing individual users to bring their own key.
@@ -96,6 +96,14 @@ while allowing individual users to bring their own key.
> When a BYOK credential is present, [key failover](./providers.md#key-failover) > When a BYOK credential is present, [key failover](./providers.md#key-failover)
> is skipped. > is skipped.
Coder Agents requests routed through AI Gateway are in-process control plane
requests, not external client requests that send their own AI Gateway bearer
token. Coder Agents use this same global BYOK setting. When BYOK is enabled,
users can save personal API keys for any enabled AI provider from the Agents
settings page. See
[Agents credential selection](../agents/models.md#credential-selection)
for the Agents-specific behavior.
Visit individual [client pages](./clients/index.md) for configuration details. Visit individual [client pages](./clients/index.md) for configuration details.
### Enable or disable BYOK ### Enable or disable BYOK
docs/ai-coder/ai-gateway/clients/coder-agents.md
-199
View File
@@ -1,199 +0,0 @@
# Coder Agents
[Coder Agents](../../agents/index.md) is a chat interface and API for delegating
development work to coding agents that run inside the Coder control plane. When
AI Gateway is enabled on the same deployment, Coder Agents traffic can be
routed through it for full audit and governance coverage.
## Prerequisites
- AI Gateway is [enabled](../setup.md#activation) on your Coder deployment.
- At least one [provider](../setup.md#configure-providers) is configured in
AI Gateway with a valid upstream key.
- You are an administrator with permission to configure Coder Agents
[providers](../../agents/models.md#providers).
> [!NOTE]
> AI Gateway and Coder Agents use independent provider configurations. Adding
> a provider to AI Gateway does not enable it in Coder Agents, and vice versa.
> Configure each separately.
## Configuration
Point each Agents provider's **Base URL** at your local AI Gateway endpoint
and set the **API Key** to a credential AI Gateway accepts. Because both
services run in the same `coderd` process, the AI Gateway endpoint is just
your deployment URL plus `/api/v2/aibridge/<provider>`.
The steps are the same regardless of provider type, only the Base URL
changes:
1. Open the Coder dashboard and navigate to the **Agents** page.
1. Click **Admin**, then select the **Providers** tab.
1. Click the provider you want to route through AI Gateway.
1. Set the **Base URL** using the table below.
1. Set the **API Key** to a Coder API token. See
[Authentication](#authentication) for which token to use.
1. Click **Save**.
| Agents provider | Base URL |
|-------------------------------------------|-------------------------------------------------------|
| Anthropic | `https://coder.example.com/api/v2/aibridge/anthropic` |
| OpenAI | `https://coder.example.com/api/v2/aibridge/openai/v1` |
| OpenAI Compatible (named OpenAI instance) | `https://coder.example.com/api/v2/aibridge/<name>/v1` |
Replace `coder.example.com` with your Coder deployment URL.
To target a [named AI Gateway instance](../setup.md#multiple-instances-of-the-same-provider)
through the **Anthropic** or **OpenAI** providers, swap the provider segment
of the Base URL for the instance name. For example, an Anthropic instance
named `anthropic-corp` becomes
`https://coder.example.com/api/v2/aibridge/anthropic-corp`, and an OpenAI
instance named `azure-openai` becomes
`https://coder.example.com/api/v2/aibridge/azure-openai/v1`.
> [!NOTE]
> The table above covers the Coder Agents provider types most commonly
> routed through AI Gateway. Coder Agents also supports Azure OpenAI,
> AWS Bedrock, Google, OpenRouter, and Vercel AI Gateway provider types,
> but only providers that speak a wire protocol AI Gateway supports
> (Anthropic, OpenAI, or Copilot today) can be routed through it. The
> base URL pattern is the same for any compatible provider: point it at
> `https://<your-coder-host>/api/v2/aibridge/<instance-name>`.
After saving, [add or update a model](../../agents/models.md#add-a-model) on
each provider so developers can select it from the chat. Models from a
provider only appear in the model selector once the provider has valid
credentials.
## Authentication
AI Gateway accepts Coder-issued tokens for client authentication and also
supports [Bring Your Own Key
(BYOK)](../auth.md#bring-your-own-key-byok) for other clients.
Coder Agents only uses the centralized key mode today. The upstream
provider keys you configured for AI Gateway (for example,
`CODER_AI_GATEWAY_OPENAI_KEY`) are used by AI Gateway internally to call the
upstream provider; they are not what Coder Agents sends.
Coder Agents stores the **API Key** field on each provider as the bearer
credential it forwards to AI Gateway on every request from any chat that
uses that provider. AI Gateway resolves the bearer token to a Coder user
and uses **that user** as the initiator on every interception.
Because the Agents provider config is deployment-wide, every chat that
uses this provider is logged in AI Gateway under the identity of whoever
owns the API token configured here. Per-chat attribution to the developer
who started a chat is **not** preserved when routing Agents traffic
through AI Gateway today. See
[Known limitations](#known-limitations) below.
For that reason, **use a long-lived API token for a dedicated
[service account](../../../admin/users/headless-auth.md#create-a-service-account)**
that is intended to represent Agents traffic in audit. Avoid using an
admin's personal token: every chat would otherwise appear to have been
initiated by that admin.
> [!NOTE]
> Coder Agents does not support Bring Your Own Key when routing through
> AI Gateway today, but we plan to unify these authentication modes in a
> future release. For now, the Agents [User API
> keys](../../agents/models.md#user-api-keys-byok) feature is independent
> of AI Gateway and applies to direct provider calls only.
## Identity and correlation headers
When Coder Agents calls a provider, it attaches identity headers to every
outgoing request. Today AI Gateway uses two of them:
| Header | Used by AI Gateway today |
|-------------------|--------------------------------------------------------------------------------------------------------------------------|
| `User-Agent` | Detects Coder Agents traffic and labels sessions with the `Coder Agents` client name. |
| `X-Coder-Chat-Id` | Acts as the AI Gateway session key, so every interception in a chat (and its sub-agents) appears under a single session. |
Coder Agents also sends `X-Coder-Owner-Id`, `X-Coder-Subchat-Id`, and
`X-Coder-Workspace-Id`. These are emitted for forward compatibility but
are not consumed by AI Gateway today, which is why per-developer
attribution is not preserved. See
[Known limitations](#known-limitations) for details.
You don't need to configure these headers; they are set automatically.
## Pre-configuring in templates
You don't need to configure anything inside workspaces for Coder Agents
itself to use AI Gateway. The agent loop runs in the control plane, so
the Agents provider's Base URL is the only place AI Gateway needs to be
wired up.
If you also want IDE-based clients running inside Agents-provisioned
workspaces (such as Claude Code or Codex CLI) to route through AI
Gateway, configure them on the workspace template. See the
[Configuring In-Workspace Tools](./index.md#configuring-in-workspace-tools)
section for the general pattern, plus the per-client pages such as
[Claude Code](./claude-code.md#pre-configuring-in-templates).
## Verifying the integration
After saving the provider, start a new chat from the Agents page and send
a short prompt. Then:
1. Open the AI Gateway sessions UI at
`https://coder.example.com/aibridge/sessions`.
1. The most recent session should show **Coder Agents** as the client and
the user that owns the API token configured on the Agents provider as
the initiator.
1. Click into the session to see the chat's interceptions, token usage,
and any tool invocations.
If the session does not appear, check that the Agents provider's Base URL
points at your deployment's `/api/v2/aibridge/...` path and that the API
key is a valid Coder token.
## Troubleshooting
- **`401 Unauthorized` from the chat.** The API key on the Agents provider
is not a valid Coder token, has been revoked, or belongs to a user that
cannot reach AI Gateway. Generate a new long-lived token and update the
provider.
- **Sessions in audit show a generic client instead of Coder Agents.**
This usually means the request bypassed AI Gateway. Confirm the
provider's Base URL starts with your deployment's `/api/v2/aibridge/`
path and not the upstream provider URL.
- **Provider does not appear in the Agents model selector.** Add at least
one [model](../../agents/models.md#add-a-model) to the provider after
saving the Base URL. Providers without an enabled model are hidden from
developers.
- **"Chat interrupted" error when resuming a conversation.**
This occurs when the API key that was used to start a chat turn is no
longer available. Common causes: upgrading from a version before
`api_key_id` tracking was introduced, or deleting an API key while a
chat is active. The error is self-healing: send your message again and
the new message will use your current API key. If the error persists
after resending, this indicates a bug. Please report it.
## Known limitations
- **Per-developer attribution is not preserved.** AI Gateway attributes
every interception to the user that owns the bearer token configured
on the Agents provider, regardless of which developer started the
chat. The chat owner ID is sent by Coder Agents in `X-Coder-Owner-Id`
but is not consumed by AI Gateway today. Use a dedicated service
account for the Agents provider's API token so audit data is
attributed to a single, non-human identity.
- **Bring Your Own Key (BYOK) is not supported through AI Gateway.**
Personal LLM credentials configured under
[User API keys](../../agents/models.md#user-api-keys-byok) are sent
directly to the provider; AI Gateway is not involved when BYOK is
active.
## Related documentation
- [Coder Agents: Models and providers](../../agents/models.md) for the
full reference on configuring providers in Agents.
- [Coder Agents: Using an LLM proxy](../../agents/models.md#using-an-llm-proxy)
for the short version of this same configuration.
- [AI Gateway setup](../setup.md) for enabling AI Gateway and
configuring upstream provider credentials.
- [Auditing AI sessions](../audit.md) for how AI Gateway groups Coder
Agents traffic into sessions.
docs/ai-coder/ai-gateway/clients/index.md
+1 -2
View File
@@ -36,8 +36,7 @@ For information about authenticating with AI Gateway, visit [AI Gateway Authenti
The table below shows tested AI clients and their compatibility with AI Gateway. The table below shows tested AI clients and their compatibility with AI Gateway.
| Client | OpenAI | Anthropic | BYOK | Notes | | Client | OpenAI | Anthropic | BYOK | Notes |
|-----------------------------------|--------|-----------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------| |----------------------------------|--------|-----------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Coder Agents](./coder-agents.md) | ✅ | ✅ | ❌ | First-class AI Gateway client. Uses the Coder Agents [provider config](../../agents/models.md#providers). |
| [Mux](./mux.md) | ✅ | ✅ | - | | | [Mux](./mux.md) | ✅ | ✅ | - | |
| [Claude Code](./claude-code.md) | - | ✅ | ✅ | | | [Claude Code](./claude-code.md) | - | ✅ | ✅ | |
| [Codex CLI](./codex.md) | ✅ | - | ✅ | | | [Codex CLI](./codex.md) | ✅ | - | ✅ | |
docs/manifest.json
-6
View File
@@ -1170,12 +1170,6 @@
"path": "./ai-coder/ai-gateway/clients/index.md", "path": "./ai-coder/ai-gateway/clients/index.md",
"state": ["ai governance add-on"], "state": ["ai governance add-on"],
"children": [ "children": [
{
"title": "Coder Agents",
"description": "Route Coder Agents traffic through AI Gateway",
"path": "./ai-coder/ai-gateway/clients/coder-agents.md",
"state": ["ai governance add-on"]
},
{ {
"title": "Claude Code", "title": "Claude Code",
"description": "Configure Claude Code to use AI Gateway", "description": "Configure Claude Code to use AI Gateway",