From a8a01aab1db37694ea3c7827436fbcf4d99e900f Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 26 Oct 2026 12:09:34 +0000 Subject: [PATCH] [Automated] Draft docs (kagent): feat: support gateway token passthrough for embedded controllers Signed-off-by: GitHub Action --- .../1.x/about/substrate-runtime/networking-and-egress.md | 8 ++++++++ .../1.x/setup/model-providers/about-model-providers.md | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs-site/content/kagent/1.x/about/substrate-runtime/networking-and-egress.md b/docs-site/content/kagent/1.x/about/substrate-runtime/networking-and-egress.md index d7de0ea7..f75168bf 100644 --- a/docs-site/content/kagent/1.x/about/substrate-runtime/networking-and-egress.md +++ b/docs-site/content/kagent/1.x/about/substrate-runtime/networking-and-egress.md @@ -123,3 +123,11 @@ A credential is declared on a rule as a `replace_headers` entry. The entry names Replacement happens only on a connection that the gateway terminates, and only when a credential provider is configured for the reference. If either is missing, the request reaches the destination without the credential. The request fails closed when replacement is attempted and fails. `403` is returned when the provider does not hold the credential or refuses to release it, and `503` is returned when the provider is unreachable. Replacement also works on a cleartext `http` rule, where the gateway does not originate TLS to the destination. The credential is then readable by anything on the path between the gateway and the destination unless something outside the gateway encrypts that segment. Prefer an `https` destination for any host that takes a credential. + +### Caller-token passthrough through the gateway {#caller-token-passthrough-through-the-gateway} + +A ModelConfig or RemoteMCPServer can set `tokenPassthrough: true`. The revision then records each passthrough client as a target with an exact origin, header, and prefix. In a default kagent controller, the runtime sends the caller token in that target header. The gateway does not replace the token. + +An embedding controller can register `app.Options.EgressPolicyCompilers` and keep the caller token out of the runtime. In this deployment model, the controller's authenticator gives the runtime the placeholder `kagent-credential-injected`. The egress policy compilers bind each target header to the caller token at the gateway. The compilers run after kagent builds the normal allowlist. They can change the compiled policy before kagent validates the policy. + +When any egress policy compiler is registered, every passthrough target must have a credential header on its origin. If a compiler fails or validation fails, kagent applies a deny-all egress policy to the Actor until a retry succeeds. A passthrough target also reserves its origin against Secret-backed credentials. The reservation also applies to clients at the same origin that do not opt in to `tokenPassthrough`. diff --git a/docs-site/content/kagent/1.x/setup/model-providers/about-model-providers.md b/docs-site/content/kagent/1.x/setup/model-providers/about-model-providers.md index b1c15636..8daa493b 100644 --- a/docs-site/content/kagent/1.x/setup/model-providers/about-model-providers.md +++ b/docs-site/content/kagent/1.x/setup/model-providers/about-model-providers.md @@ -26,7 +26,7 @@ Credentials come from a Kubernetes Secret in the same namespace as the ModelConf Set `tokenPassthrough: true` to send the bearer token from the incoming agent-to-agent (A2A) request to the provider as the API key, rather than reading a key from a Secret. A ModelConfig cannot set both `tokenPassthrough` and `apiKeySecret`. The setting is not available for the `Gemini`, `GeminiVertexAI`, or `AnthropicVertexAI` providers, or on a `codex` or `claude` Harness. -The egress gateway injects no credential for the provider's host, so the caller's token reaches the provider unchanged. kagent also refuses to attach a static credential to that host. +In a default kagent controller, the egress gateway injects no credential for the provider's host. The caller's token reaches the provider unchanged. An embedding controller can register egress policy compilers that bind the caller token at the gateway. kagent refuses to attach a static credential to the provider's host in either setup. Every model and MCP server that an agent reaches at the provider's origin must also forward the caller's token. Otherwise, the Agent reports the `Compatible` condition as `False`, with a message such as `destination "https://api.openai.com:443" mixes tokenPassthrough with clients that do not use it`. The condition is also `False` when a model or MCP server at that origin sets its own value for the header that the token replaces.