docs: add Coder Agents AI Gateway client page#24829
Conversation
Adds a dedicated AI Gateway client page documenting how to route Coder Agents traffic through AI Gateway, including provider configuration, authentication, identity/correlation headers, in-template guidance, and verification steps. Lists Coder Agents first under the Client Configuration sub-pages and adds it to the compatibility table in the clients index. Closes CODAGT-157 (partial: temporary doc on configuring AI Gateway with Agents). Generated by Coder Agents on behalf of David Fraley.
Docs preview |
…rush to client filter values The `/api/v2/aibridge/sessions?client=` query filter accepts the exact string values defined as `Client` constants in `aibridge/client.go`. Two of those constants (`Coder Agents`, added when Coder Agents was wired up as a first-class AI Gateway client, and `Charm Crush`) were missing from the documented list. No code change is needed. The values already match the SQL filter in `coderd/database/queries/aibridge.sql`: COALESCE(ai.client, 'Unknown') = @client::text Generated by Coder Agents on behalf of David Fraley.
…nted client filter values Charm Crush is a recognized aibridge.Client constant, but we have no client config page or compatibility-table entry for it. Listing it here without a companion config page is misleading: users would learn the filter value exists but have no way to set up the client to begin with. Removing it from the documented filter list keeps the doc aligned with configurable client coverage. The constant remains in aibridge/client.go and the SQL filter still accepts the literal string if a caller already knows it. Generated by Coder Agents on behalf of David Fraley.
… Compatible guidance Reflect what AI Gateway actually does for Coder Agents traffic and fix inaccurate guidance in the configuration tabs. - Authentication: AI Gateway resolves the bearer token to a Coder user and uses that user (not the chat owner) as the initiator. Strongly recommend a service-account token instead of an admin token. - Identity headers: only User-Agent and X-Coder-Chat-Id are consumed by AI Gateway today. Note that X-Coder-Owner-Id, X-Coder-Subchat-Id, and X-Coder-Workspace-Id are emitted but not yet read. - OpenAI Compatible: drop the misleading multi-instance Anthropic example. OpenAI Compatible speaks the OpenAI wire protocol, so it cannot target Anthropic-typed instances. Document its actual use case (opting out of OpenAI-specific options on a named OpenAI-typed instance) and add inline guidance under the OpenAI and Anthropic tabs for targeting named instances via the matching provider type. - Verifying the integration: the initiator shown is the API token's user, not the chat owner. - Add a Known limitations section covering the attribution gap and BYOK exclusion. Generated by Coder Agents on behalf of David Fraley.
…o a single procedure The Anthropic, OpenAI, and OpenAI Compatible tabs all walked through the same six-step procedure with only the Base URL differing. Replace the three tabs with one procedure and a Base URL reference table. Move the OpenAI Compatible 'when to use' guidance into its own subsection linked from the table, since it's the one provider type that needs extra context (it speaks the OpenAI wire protocol regardless of the upstream provider on AI Gateway). Generated by Coder Agents on behalf of David Fraley.
…bution wording and clarify provider scope - Tighten the 'Identity and correlation headers' section so it explicitly ties X-Coder-Owner-Id (and the other unconsumed Coder headers) to the attribution gap and links to Known limitations. The behavior was already accurate; this just makes the cause/effect chain explicit. - Drop the broken anchor link in the Configuration table (#when-to-use-openai-compatible was removed in a prior commit). - Add a note that the documented provider examples (Anthropic, OpenAI, OpenAI Compatible) are not exhaustive. Coder Agents also supports Azure OpenAI, AWS Bedrock, Google, OpenRouter, and Vercel AI Gateway provider types, but routing through AI Gateway is bounded by the wire protocols AI Gateway speaks (Anthropic, OpenAI, Copilot today). Generated by Coder Agents on behalf of David Fraley.
|
Re-verified the attribution behavior against the code and pushed a follow-up commit (24d54df). Verification of attribution behaviorTraced the request lifecycle to confirm what
So: AI Gateway today attributes every interception to the bearer-token's resolved user, and What I changedThe contradiction described offline turned out to already be resolved on this branch in a011fab — the Identity and correlation headers section already said
Validation
|
| AI Gateway only accepts Coder-issued tokens for client authentication. The | ||
| upstream provider keys you configured for AI Gateway (for example, | ||
| `CODER_AIBRIDGE_OPENAI_KEY`) are used by AI Gateway internally to call the | ||
| upstream provider; they are not what Coder Agents sends. |
There was a problem hiding this comment.
This isn't entirely true, we also allow people to specify their own key, and then the bridge key is required as a header
https://coder.com/docs/ai-coder/ai-gateway/clients#bring-your-own-key-byok
https://coder.com/docs/ai-coder/ai-gateway/clients/claude-code
There was a problem hiding this comment.
It sounds like this version of Agents+AI Bridge doesn't work with BYOK though May be worth just clarifyin that point.
There was a problem hiding this comment.
Ya we aren't using Agent's BYOK, at least rn.
There was a problem hiding this comment.
feel to merge, i just read this whole section as a bit confusing/misleading. perhaps a more simple approach which is bridge's authentication is handled via single key meaning user keys are neglected for now.
There was a problem hiding this comment.
Good catch. Updated the opening of the Authentication section to acknowledge BYOK exists in AI Gateway and clarify that Agents only uses centralized key mode today. Also updated the BYOK note to signal we plan to unify these auth modes in a future release.
See 2632131.
Generated by Coder Agents.
Summary
Adds a dedicated AI Gateway client documentation page for Coder Agents at
docs/ai-coder/ai-gateway/clients/coder-agents.md. Coder Agents is a first-class AI Gateway client (auto-detected via thecoder-agents/user-agent) but had no entry in the Client Configuration sub-pages until now.The new page covers:
X-Coder-Owner-Id,X-Coder-Chat-Id,X-Coder-Subchat-Id, andX-Coder-Workspace-Idcorrelation headers that AI Gateway uses to group interceptions into sessions.agents/models.md, the AI Gateway audit page, and the AI Gateway setup page.Also:
docs/manifest.json.docs/ai-coder/ai-gateway/clients/index.md.Closes CODAGT-157 (partial: "A temporary doc on configuring AI Bridge/AI Gateway with Agents").
Proof
This PR is markdown-only, so the visible UI/UX change is the rendered docs page and the updated compatibility table.
Locally rendered preview screenshots (new page + clients index with the new row highlighted) are attached to the originating chat in this Coder Agents session for review. They are not committed to the repo because they are local-render artifacts only; the production rendering will follow the coder.com docs site styling.
If you want them inline here, drop them into a comment after merge or grab them from the chat attachments.
Validation
pnpm run format-docs- clean (no changes to apply).pnpm run lint-docs- 0 errors across 459 files.make pre-commit(light) ran via the pre-commit hook. All checks pass; the only emdash flagged is pre-existing in the unmodified portion ofclients/index.md.Docs CIworkflow on this branch: success.python3 -c "import json; json.load(open('docs/manifest.json'))"- manifest is valid JSON.Decision log
X-Coder-Owner-Id, not the token owner..preview/(untracked) so we don't ship local render output. The docs site renders these markdown files itself.docs/manifest.jsonanddocs/ai-coder/ai-gateway/clients/, so per AGENTS.md the narrowest scope containing every changed file isdocs.Generated by Coder Agents (this is a bot responding on @davidfraley's behalf).