3.2 Routing an agent through Gateway

Routing is what fills LLM Records, what lets Permissions hold model and provider rules, and what lets Gateway keep the vendor key instead of the agent.

The two waysCopy Anchor Link

Gateway writes the agent's configurationCopy Anchor Link

Agents → open an agent → pick a provider → Write configuration.

For an agent whose configuration format Gateway knows, this puts the endpoint and token in the agent's own file, in that agent's format.

• Preview shows exactly what will be written, first.
• Restore undoes it.
• Picking a different provider afterwards rewrites the file on the spot, so switching from then on is one click, from either page.

You export two variablesCopy Anchor Link

For any other agent, the page shows an environment snippet with the real values already filled in. Start the agent from a shell that has it:

export ANTHROPIC_BASE_URL="http://localhost:17000/v1/agents/claude-code"
export ANTHROPIC_AUTH_TOKEN="cg-..."

That token is Gateway's own relay token, not a vendor key. The agent refuses to start without something in that variable, and Gateway authenticates upstream with the provider's key instead.

One base URL, four APIsCopy Anchor Link

The agent's base URL is /v1/agents/<agent-id>, and what it answers depends on the path the client asks for:

The API the provider serves need not be the same one. Gateway translates between all four, in both directions, and for streamed answers too. Which is what makes these work:

• Codex on DeepSeek, Kimi or Qwen.
• Claude Code on any of them.
• The Gemini CLI on a provider that never heard of Google's API.

A provider serving the very API the request arrived in is relayed byte for byte, untouched, since there is nothing to translate.

The one thing Gateway answers itself is the token count an Anthropic or Gemini client asks for before each turn, which it estimates when the bound provider has no endpoint to ask.

What happens to a requestCopy Anchor Link

1. Authenticated — the relay token, unless the request came from this machine (5.2).
2. Checked — against that agent's permissions: the model, the provider, and the tools in the request (4.1). A tool that is switched off is taken out of the request before it leaves this machine.
3. Planned — which provider answers, and under which model name, down to what it degrades to if that one cannot (3.6).
4. Translated, if the provider speaks a different API.
5. Relayed, with the provider's key, failing over down the plan until one answers.
6. Recorded, to the depth llmRecordMode says (4.2).

A request that asks for something switched off comes back as a permission_error in the API the agent speaks, so it reads as a refusal rather than as a broken gateway.

Changing a key laterCopy Anchor Link

Once agents point at Gateway, the key lives in one place. Edit the provider, and every agent bound to it picks up the change on its next request — no agent configuration is touched.

Next: 3.3 No API key: the caller's own login.