Skip to content

docs: add Coder Agents AI Gateway client page#24829

Merged
david-fraley merged 9 commits into
mainfrom
dfraley/codagt-157-docs-aigateway-coder-agents-clients
May 5, 2026
Merged

docs: add Coder Agents AI Gateway client page#24829
david-fraley merged 9 commits into
mainfrom
dfraley/codagt-157-docs-aigateway-coder-agents-clients

Conversation

@david-fraley
Copy link
Copy Markdown
Collaborator

@david-fraley david-fraley commented Apr 29, 2026

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 the coder-agents/ user-agent) but had no entry in the Client Configuration sub-pages until now.

The new page covers:

  • Pre-requisites and the relationship between AI Gateway provider config and Coder Agents provider config (they're independent).
  • Step-by-step base-URL setup for Anthropic, OpenAI, and OpenAI Compatible (named instances) providers.
  • Authentication: only Coder-issued tokens are accepted, recommends a service-account long-lived token.
  • The X-Coder-Owner-Id, X-Coder-Chat-Id, X-Coder-Subchat-Id, and X-Coder-Workspace-Id correlation headers that AI Gateway uses to group interceptions into sessions.
  • Pre-configuring in templates (no workspace setup needed for Agents itself; in-workspace clients still configured the existing way).
  • Verification via the AI Gateway sessions UI and a short troubleshooting section.
  • Cross-links to agents/models.md, the AI Gateway audit page, and the AI Gateway setup page.

Also:

  • Lists the Coder Agents page first under the Client Configuration sub-pages in docs/manifest.json.
  • Adds a Coder Agents row (top of the list) to the compatibility table in 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 of clients/index.md.
  • Docs CI workflow on this branch: success.
  • python3 -c "import json; json.load(open('docs/manifest.json'))" - manifest is valid JSON.
Decision log
  • First in the sub-page list and first row in the compatibility table. Reviewer-requested ordering. Coder Agents is the most likely entry point for customers who already have AI Gateway and want to wire it up to Agents.
  • No BYOK section. Coder Agents does not currently send a separate BYOK credential when calling AI Gateway; the Agents User API keys feature is independent and is for direct provider calls. Documented this explicitly.
  • Service-account token recommended over admin token. The provider API key is deployment-wide, so any chat using this provider sends the same token to AI Gateway. AI Gateway attributes the request to the chat owner via X-Coder-Owner-Id, not the token owner.
  • No commit-time generated artifacts. Screenshots stay in .preview/ (untracked) so we don't ship local render output. The docs site renders these markdown files itself.
  • PR title scope. Changes span docs/manifest.json and docs/ai-coder/ai-gateway/clients/, so per AGENTS.md the narrowest scope containing every changed file is docs.

Generated by Coder Agents (this is a bot responding on @davidfraley's behalf).

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.
@github-actions
Copy link
Copy Markdown

Docs preview

📖 View docs preview

@david-fraley david-fraley changed the title docs(ai-coder/ai-gateway/clients): add Coder Agents client page docs: add Coder Agents AI Gateway client page Apr 29, 2026
…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.
Copy link
Copy Markdown
Collaborator Author

Re-verified the attribution behavior against the code and pushed a follow-up commit (24d54df).

Verification of attribution behavior

Traced the request lifecycle to confirm what InitiatorID is actually populated from:

  1. enterprise/aibridged/http.go:97-111 calls client.IsAuthorized(ctx, &proto.IsAuthorizedRequest{Key: key}) where key is the bearer token extracted from the request, then wraps the context: r = r.WithContext(aibridge.AsActor(ctx, resp.GetOwnerId(), ...)).
  2. enterprise/aibridgedserver/aibridgedserver.go:564-611 (IsAuthorized) validates the API token, looks up key.UserID, and returns OwnerId: key.UserID.String(). The OwnerId is the bearer-token's user, not the chat owner.
  3. aibridge/bridge.go:201 reads actor := aibcontext.ActorFromContext(ctx), then aibridge/bridge.go:218 and aibridge/bridge.go:225 populate InitiatorID: actor.ID on the recorder and the InterceptionRecord.
  4. X-Coder-Owner-Id is set in coderd/x/chatd/chatprovider/chatprovider.go:1118 but searching all of aibridge/, coderd/, and enterprise/ shows it is never read. Only X-Coder-Chat-Id is consumed (aibridge/session.go:77 via GuessSessionID).

So: AI Gateway today attributes every interception to the bearer-token's resolved user, and X-Coder-Owner-Id is correlation-only / forward-compatible. That matches what the existing doc said in Authentication and Known limitations.

What I changed

The contradiction described offline turned out to already be resolved on this branch in a011fab — the Identity and correlation headers section already said X-Coder-Owner-Id is "emitted for forward compatibility but [is] not consumed by AI Gateway today." The remaining gaps were smaller:

  1. Tightened the headers section. Made the cause/effect explicit and added an inline cross-reference to Known limitations so the reader sees the link between the unconsumed header and the attribution gap.
  2. Fixed a broken anchor link. The Configuration table linked to #when-to-use-openai-compatible, a section that was removed in ca11b3a. Removed the link; markdownlint passes now.
  3. Added a non-exhaustive provider note. coderd/x/chatd/chatprovider/chatprovider.go:25-34 shows Coder Agents supports 8 providers (Anthropic, Azure OpenAI, AWS Bedrock, Google, OpenAI, OpenAI Compatible, OpenRouter, Vercel AI Gateway). I called out the additional five and added an honest scope caveat: AI Gateway only speaks Anthropic, OpenAI, and Copilot wire protocols today (aibridge/config/config.go:5-9, plus aibridge/provider/{anthropic,openai,copilot}.go), so not every Agents provider can be routed through it. The base URL pattern is the same wherever it does work.

Validation

  • pnpm exec markdownlint-cli2 docs/ai-coder/ai-gateway/clients/coder-agents.md — 0 errors
  • pnpm exec markdown-table-formatter docs/ai-coder/ai-gateway/clients/coder-agents.md — clean
  • bash scripts/check_emdash.sh — OK
  • make pre-commit-light (via the pre-commit hook) — passed

This is Coder Agents responding on @david-fraley's behalf.

Comment on lines +71 to +74
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.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It sounds like this version of Agents+AI Bridge doesn't work with BYOK though May be worth just clarifyin that point.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ya we aren't using Agent's BYOK, at least rn.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@david-fraley david-fraley merged commit 526059e into main May 5, 2026
26 checks passed
@david-fraley david-fraley deleted the dfraley/codagt-157-docs-aigateway-coder-agents-clients branch May 5, 2026 16:39
@github-actions github-actions Bot locked and limited conversation to collaborators May 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants