diff --git a/docs/ai-coder/agents/getting-started.md b/docs/ai-coder/agents/getting-started.md index 8258ed44ad..a513cba745 100644 --- a/docs/ai-coder/agents/getting-started.md +++ b/docs/ai-coder/agents/getting-started.md @@ -37,11 +37,13 @@ Before you begin, confirm the following: To configure Coder Agents: -1. Navigate to the **Agents** page in the Coder dashboard. -1. Open **Settings** > **Manage Agents** and select the **Providers** tab. - Pick a provider, enter your API key, and save. -1. Switch to the **Models** tab, click **Add**, and configure at least one - model with its identifier, display name, and context limit. +1. Navigate to **Admin settings** > **AI** and select **Providers**. +1. Add or update a provider with its credentials and upstream endpoint, then + save it. +1. Navigate to the **Agents** page, open **Settings** > **Manage Agents**, and + 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. Detailed instructions for each provider and model option are in the diff --git a/docs/ai-coder/agents/models.md b/docs/ai-coder/agents/models.md index a9a6c7bf38..9e29f621db 100644 --- a/docs/ai-coder/agents/models.md +++ b/docs/ai-coder/agents/models.md @@ -1,77 +1,87 @@ # Models -Administrators configure LLM providers and models from the Coder dashboard. -Providers, models, and centrally managed credentials are deployment-wide -settings managed by platform teams. Developers select from the set of models -that an administrator has enabled. +Administrators configure LLM providers from **Admin settings** > **AI** and +Coder Agents models from the **Agents** settings page. Providers, models, and +centrally managed credentials are deployment-wide settings managed by platform +teams. Developers select from the set of models that an administrator has +enabled. -Optionally, administrators can allow developers to supply their own API keys -for specific providers. See [User API keys](#user-api-keys-byok) below. +Optionally, administrators can enable AI Gateway Bring Your Own Key (BYOK) +so developers can supply personal API keys for providers. See +[User API keys](#user-api-keys-byok) below. ## 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: -| Provider | Description | -|-------------------|------------------------------------------------------------------| -| Anthropic | Claude models via Anthropic API | -| OpenAI | GPT and o-series models via OpenAI API | -| Google | Gemini models via Google AI API | -| Azure OpenAI | OpenAI models hosted on Azure | -| AWS Bedrock | Models via AWS Bedrock (bearer token or ambient AWS credentials) | -| OpenAI Compatible | Any endpoint implementing the OpenAI API | -| OpenRouter | Multi-model routing via OpenRouter | -| Vercel AI Gateway | Models via Vercel AI SDK | +| Provider | Description | +|-------------------|------------------------------------------| +| Anthropic | Claude models via Anthropic API | +| OpenAI | GPT and o-series models via OpenAI API | +| Google | Gemini models via Google AI API | +| Azure OpenAI | OpenAI models hosted on Azure | +| AWS Bedrock | Models via AWS Bedrock | +| OpenAI Compatible | Any endpoint implementing the OpenAI API | +| OpenRouter | Multi-model routing via OpenRouter | +| Vercel AI Gateway | Models via Vercel AI SDK | 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 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 -1. Navigate to the **Agents** page in the Coder dashboard. -1. Open **Settings** > **Manage Agents** and select the **Providers** tab. -1. Click the provider you want to configure. -1. Enter the **API key** for the provider, if required. -1. Optionally set a **Base URL** to override the default endpoint. This is - useful for enterprise proxies, regional endpoints, or self-hosted models. +LLM providers are managed from the deployment AI settings, not from the Agents +settings page. + +1. Navigate to **Admin settings** > **AI**. +1. Select **Providers**. +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**. -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). -The providers list shows all supported providers and their configuration -status. +## Endpoint/base URL for OpenAI-compatible providers -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. -Adding a provider usually requires an API key. AWS Bedrock can also use -ambient AWS credentials. The base URL is optional. +For the default Agents path through AI Gateway, set the endpoint/base URL to +the upstream provider or proxy endpoint. Do not set it to Coder's public AI +Gateway route, such as `https:///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 - **API key** field when you add the provider. -- **Ambient AWS credentials mode**: Leave the **API key** field empty. The - Coder server resolves credentials from the standard AWS SDK credential chain, - including IAM instance roles and `AWS_ACCESS_KEY_ID` / - `AWS_SECRET_ACCESS_KEY` environment variables. +| Provider type | Example endpoint/base URL | +|-------------------------------------|------------------------------------------------------------| +| OpenAI | `https://api.openai.com/v1/` | +| Azure OpenAI | `https://.openai.azure.com/openai/v1` | +| Google Gemini OpenAI-compatible API | `https://generativelanguage.googleapis.com/v1beta/openai/` | +| 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 -`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. +Confirm the exact endpoint/base URL in your provider or proxy documentation. ## 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 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 access to LLM providers. See [Architecture](./architecture.md#no-api-keys-in-workspaces) for details on this security model. -## Key policy +## Credential selection -Each provider has three policy flags that control how provider credentials are -sourced: +Coder Agents use the AI providers configured by administrators. Provider API +keys entered by administrators are centralized credentials for the deployment. -| Setting | Default | Description | -|-------------------------|---------|--------------------------------------------------------------------------------------------------------------------------| -| Central API key | On | The provider uses deployment-managed credentials configured by an administrator. For most providers, this is an API key. | -| Allow user API keys | Off | Developers may supply their own API key for this provider. | -| 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. | +BYOK for Coder Agents is controlled by the +[global AI Gateway BYOK setting](../ai-gateway/auth.md#bring-your-own-key-byok), +not by per-provider key policy flags. When BYOK is enabled, users can save a +personal API key for any enabled AI provider. When BYOK is disabled, saved user +keys are ignored and users cannot add or update personal keys. -At least one credential source must be enabled. These settings appear in the -provider configuration form under **Key policy**. +For each provider request, Coder selects credentials in this order: -The interaction between these flags determines whether a provider is available -to a given developer: - -| Central key | User keys allowed | Fallback | Developer has key | Result | -|-------------|-------------------|----------|-------------------|----------------------| -| On | Off | — | — | Uses central key | -| 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. +1. If BYOK is enabled and the user has saved a personal key for the selected + provider, Coder uses the user's key. +1. Otherwise, Coder uses centralized provider credentials when they are + configured. +1. If neither a usable user key nor centralized credentials are available, the + provider is unavailable for that user. ## Models @@ -131,11 +124,11 @@ generation parameters, and provider-specific options. 1. Open **Settings** > **Manage Agents** and select the **Models** tab. 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`). 1. Set a **Display Name** so developers see a human-readable label in the model 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). 1. Configure any provider-specific options (see below). 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`). | | 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. | -| 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. | | Temperature | Controls randomness. Lower values produce more deterministic output. | | Top P | Nucleus sampling threshold. | @@ -238,9 +231,9 @@ are active. The model selector uses the following precedence to pre-select a model: -1. **Last used model** — stored in the browser's local storage. -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. **Last used model**, stored in the browser's local storage. +1. **Admin-designated default**, the model marked with the star icon. +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 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) -When an administrator enables **Allow user API keys** on a provider, -developers can supply their own API key from the Agents settings page. +When [AI Gateway BYOK](../ai-gateway/auth.md#bring-your-own-key-byok) is +enabled, developers can supply personal API keys for any enabled AI provider +from the Agents settings page. ### Managing personal API keys 1. Navigate to the **Agents** page in the Coder dashboard. 1. Open **Settings** and select the **API Keys** tab. -1. Each provider that allows user keys is listed with a status indicator: - - **Key saved** — your personal key is active and will be used for requests. - - **Using shared key** — no personal key set, but the central deployment - key is available as a fallback. - - **No key** — you must add a personal key before you can use this provider. +1. Each enabled provider is listed with a status indicator: + - **Key saved**, your personal key is active and will be used for requests to + that provider. + - **Using shared key**, no personal key is set and Coder is using + 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**. Personal API keys are encrypted at rest using the same database encryption used for deployment-managed provider secrets. The dashboard never displays a 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 -Click **Remove** on the provider card in the API Keys settings tab. If -central key fallback is enabled, subsequent requests will use the shared -deployment-managed credentials. If fallback is disabled, the provider becomes -unavailable until you add a new personal key. +Click **Remove** on the provider card in the API Keys settings tab. Subsequent +requests use deployment-managed credentials when they are configured for that +provider. If no deployment-managed credential is available, add a new personal +key before you use models from that provider. ## Using an LLM proxy -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. +Organizations that route LLM traffic through a centralized proxy, such as +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: - -1. Add or edit the **OpenAI** provider. -1. Set the **Base URL** to your AI Gateway endpoint - (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. +Use the **OpenAI Compatible** provider type if your proxy serves multiple model +families through a single OpenAI-compatible endpoint. Include the proxy +provider's documented OpenAI-compatible path prefix, such as `/v1`, when +required. 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. diff --git a/docs/ai-coder/agents/platform-controls/mcp-servers.md b/docs/ai-coder/agents/platform-controls/mcp-servers.md index 15b3b5f219..6cd58ceb46 100644 --- a/docs/ai-coder/agents/platform-controls/mcp-servers.md +++ b/docs/ai-coder/agents/platform-controls/mcp-servers.md @@ -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-Workspace-Id` | Workspace associated with the chat, if any. | -These are the same headers Coder sends to LLM providers (see -[Coder agents headers](../../ai-gateway/clients/coder-agents.md)) so a -first-party MCP server can correlate a tool call back to the -originating chat. +Coder sends the same identity headers to LLM providers, so a 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 default** and should only be enabled for first-party or trusted diff --git a/docs/ai-coder/agents/tasks-to-chats-migration.md b/docs/ai-coder/agents/tasks-to-chats-migration.md index 1d78edde8f..db31d2fb4f 100644 --- a/docs/ai-coder/agents/tasks-to-chats-migration.md +++ b/docs/ai-coder/agents/tasks-to-chats-migration.md @@ -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 configured once in the control plane: -1. Navigate to the **Agents** page in the Coder dashboard. -1. Open **Settings** > **Manage Agents** > **Providers**, pick a provider, - enter your API key, and save. -1. Under **Models**, add at least one model and set it as the default. +1. Navigate to **Admin settings** > **AI** and select **Providers**. +1. Add or update a provider with its credentials and upstream endpoint, then + save it. +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. diff --git a/docs/ai-coder/ai-gateway/auth.md b/docs/ai-coder/ai-gateway/auth.md index e35e4f3d6b..d05e1c806c 100644 --- a/docs/ai-coder/ai-gateway/auth.md +++ b/docs/ai-coder/ai-gateway/auth.md @@ -88,7 +88,7 @@ In BYOK mode, users need two credentials: BYOK and centralized modes can be used together. 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, 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) > 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. ### Enable or disable BYOK diff --git a/docs/ai-coder/ai-gateway/clients/coder-agents.md b/docs/ai-coder/ai-gateway/clients/coder-agents.md deleted file mode 100644 index de0fcad927..0000000000 --- a/docs/ai-coder/ai-gateway/clients/coder-agents.md +++ /dev/null @@ -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/`. - -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//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:///api/v2/aibridge/`. - -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. diff --git a/docs/ai-coder/ai-gateway/clients/index.md b/docs/ai-coder/ai-gateway/clients/index.md index 3c5f1e2018..2020df10bf 100644 --- a/docs/ai-coder/ai-gateway/clients/index.md +++ b/docs/ai-coder/ai-gateway/clients/index.md @@ -35,26 +35,25 @@ For information about authenticating with AI Gateway, visit [AI Gateway Authenti The table below shows tested AI clients and their compatibility with AI Gateway. -| 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) | ✅ | ✅ | - | | -| [Claude Code](./claude-code.md) | - | ✅ | ✅ | | -| [Codex CLI](./codex.md) | ✅ | - | ✅ | | -| [OpenCode](./opencode.md) | ✅ | ✅ | ✅ | | -| [Factory](./factory.md) | ✅ | ✅ | ✅ | | -| [Cline](./cline.md) | ✅ | ✅ | ✅ | | -| [Kilo Code](./kilo-code.md) | ✅ | ✅ | ❌ | | -| [VS Code](./vscode.md) | ✅ | ❌ | ❌ | Only supports Custom Base URL for OpenAI. | -| [JetBrains IDEs](./jetbrains.md) | ✅ | ❌ | ❌ | Works in Chat mode via [third-party model configuration](https://www.jetbrains.com/help/ai-assistant/use-custom-models.html#provide-your-own-api-key). | -| [Zed](./zed.md) | ✅ | ✅ | ❌ | | -| [GitHub Copilot](./copilot.md) | ⚙️ | - | - | Requires [AI Gateway Proxy](../ai-gateway-proxy/index.md). Uses per-user GitHub tokens. | -| WindSurf | ❌ | ❌ | ❌ | No option to override base URL. | -| Cursor | ❌ | ❌ | ❌ | Override for OpenAI broken ([upstream issue](https://forum.cursor.com/t/requests-are-sent-to-incorrect-endpoint-when-using-base-url-override/144894)). | -| Sourcegraph Amp | ❌ | ❌ | ❌ | No option to override base URL. | -| Kiro | ❌ | ❌ | ❌ | No option to override base URL. | -| Gemini CLI | ❌ | ❌ | ❌ | No Gemini API support. Upvote [this issue](https://github.com/coder/coder/issues/24804). | -| Antigravity | ❌ | ❌ | ❌ | No option to override base URL. | +| Client | OpenAI | Anthropic | BYOK | Notes | +|----------------------------------|--------|-----------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Mux](./mux.md) | ✅ | ✅ | - | | +| [Claude Code](./claude-code.md) | - | ✅ | ✅ | | +| [Codex CLI](./codex.md) | ✅ | - | ✅ | | +| [OpenCode](./opencode.md) | ✅ | ✅ | ✅ | | +| [Factory](./factory.md) | ✅ | ✅ | ✅ | | +| [Cline](./cline.md) | ✅ | ✅ | ✅ | | +| [Kilo Code](./kilo-code.md) | ✅ | ✅ | ❌ | | +| [VS Code](./vscode.md) | ✅ | ❌ | ❌ | Only supports Custom Base URL for OpenAI. | +| [JetBrains IDEs](./jetbrains.md) | ✅ | ❌ | ❌ | Works in Chat mode via [third-party model configuration](https://www.jetbrains.com/help/ai-assistant/use-custom-models.html#provide-your-own-api-key). | +| [Zed](./zed.md) | ✅ | ✅ | ❌ | | +| [GitHub Copilot](./copilot.md) | ⚙️ | - | - | Requires [AI Gateway Proxy](../ai-gateway-proxy/index.md). Uses per-user GitHub tokens. | +| WindSurf | ❌ | ❌ | ❌ | No option to override base URL. | +| Cursor | ❌ | ❌ | ❌ | Override for OpenAI broken ([upstream issue](https://forum.cursor.com/t/requests-are-sent-to-incorrect-endpoint-when-using-base-url-override/144894)). | +| Sourcegraph Amp | ❌ | ❌ | ❌ | No option to override base URL. | +| Kiro | ❌ | ❌ | ❌ | No option to override base URL. | +| Gemini CLI | ❌ | ❌ | ❌ | No Gemini API support. Upvote [this issue](https://github.com/coder/coder/issues/24804). | +| Antigravity | ❌ | ❌ | ❌ | No option to override base URL. | | *Legend: ✅ supported, ⚙️ requires AI Gateway Proxy, ❌ not supported, - not applicable.* diff --git a/docs/manifest.json b/docs/manifest.json index 597fedaf0a..77d50b84a3 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1170,12 +1170,6 @@ "path": "./ai-coder/ai-gateway/clients/index.md", "state": ["ai governance add-on"], "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", "description": "Configure Claude Code to use AI Gateway",