From 546a92ceab8618022b1e8cb03f5910b6ee0a316d Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni Date: Mon, 26 Oct 2026 11:01:21 +0530 Subject: [PATCH 1/2] docs(agent-gateway): add forwarding headers page --- docs.json | 1 + product/agent-gateway/forwarding-headers.mdx | 173 +++++++++++++++++++ product/agent-gateway/registry.mdx | 3 + 3 files changed, 177 insertions(+) create mode 100644 product/agent-gateway/forwarding-headers.mdx diff --git a/docs.json b/docs.json index dc3eb6f86..374f6abe5 100644 --- a/docs.json +++ b/docs.json @@ -177,6 +177,7 @@ "product/agent-gateway/quickstart", "product/agent-gateway/registry", "product/agent-gateway/servers", + "product/agent-gateway/forwarding-headers", "product/agent-gateway/advanced-code-snippets-and-examples" ] }, diff --git a/product/agent-gateway/forwarding-headers.mdx b/product/agent-gateway/forwarding-headers.mdx new file mode 100644 index 000000000..8af57c882 --- /dev/null +++ b/product/agent-gateway/forwarding-headers.mdx @@ -0,0 +1,173 @@ +--- +title: Forwarding Headers +description: Pass headers from client requests through to your agents. +--- + +By default, Portkey sends only the headers configured on the agent integration to the upstream agent. Header forwarding passes selected headers from the client request through as well. Use it for distributed tracing, tenant context, or per-request metadata your agent expects. + +It works the same way as [header forwarding for MCP servers](/product/mcp-gateway/authentication/forwarding-headers), including inline renaming. + +Common scenarios: + +- **Distributed tracing.** Forward `x-request-id`, `x-trace-id` or `traceparent` to correlate logs across services. +- **Multi-tenancy.** Forward `x-tenant-id` or `x-org-id` for tenant-scoped operations. +- **User context.** Forward `x-user-id` or `x-user-role` for upstream authorization. + +--- + +## Configuration + +Set `forward_headers` in the agent integration's `configurations`, or use **Forward Caller Headers** when adding or editing an agent in the Agent Registry. + +### Shorthand (string array) + +Forward only the headers you list: + +```json +{ + "configurations": { + "forward_headers": ["x-request-id", "x-trace-id", "x-tenant-id"] + } +} +``` + +All other client headers are dropped. + +### Allowlist mode + +Entries in `headers` can be: + +- **A string**: forwards the header as-is. +- **An object** `{ "from": "", "to": "" }`: forwards the header under a new name. + +```json +{ + "configurations": { + "forward_headers": { + "mode": "allowlist", + "headers": [ + "x-trace-id", + { "from": "x-tenant-id", "to": "X-Organization-Id" } + ] + } + } +} +``` + +Here `x-trace-id` is forwarded as-is and `x-tenant-id` reaches the agent as `X-Organization-Id`. + +### All-except mode + +Forward every client header except the ones you list. String entries are excluded; object entries rename forwarded headers: + +```json +{ + "configurations": { + "forward_headers": { + "mode": "all-except", + "headers": [ + "x-internal-debug", + { "from": "x-tenant-id", "to": "X-Org-Id" } + ] + } + } +} +``` + + +`all-except` forwards more than you might expect, including the client's `Authorization` header if the integration does not set its own. Prefer an explicit allowlist when possible. + + +--- + +## Headers that are never forwarded + +These headers are dropped regardless of your configuration. + +**Protected headers**, the same list as for MCP servers. A rename is dropped if either its source or its target is protected: + +`cookie`, `set-cookie`, `x-api-key`, `x-portkey-api-key`, `api-key`, `apikey`, `x-auth-token`, `x-access-token`, `x-user-claims`, `x-user-jwt` + +**Connection headers**, which describe the client's connection to Portkey rather than Portkey's request to the agent. They are never sent to the agent, including as a rename target: + +`host`, `connection`, `keep-alive`, `proxy-connection`, `transfer-encoding`, `te`, `trailer`, `upgrade`, `content-length`, `expect`, `accept-encoding` + +Header names are matched case-insensitively. + +--- + +## Header priority + +Headers configured on the integration always win over forwarded ones: + +| Priority | Source | +|----------|--------| +| 1 (lowest) | Forwarded client headers | +| 2 | `headers` configured on the integration (authentication) | +| 3 (highest) | `passthrough_headers` configured on the integration | + +If a configured header and a forwarded header share a name, in any case, only the configured value is sent. Clients cannot override the agent's credentials. + +--- + +## Example + +**Integration configuration:** + +```json +{ + "configurations": { + "headers": { "Authorization": "Bearer " }, + "forward_headers": { + "mode": "allowlist", + "headers": [ + "A2A-Version", + "x-trace-id", + { "from": "x-user-token", "to": "x-upstream-token" } + ] + } + } +} +``` + +**Client request:** + +```sh +curl https://agents.portkey.ai/v1/agent/my-agent/a2a/jsonrpc \ + -H 'x-portkey-api-key: {PORTKEY_API_KEY}' \ + -H 'Content-Type: application/json' \ + -H 'A2A-Version: 1.0' \ + -H 'x-trace-id: trace-xyz789' \ + -H 'x-user-token: user-abc' \ + -H 'x-debug: 1' \ + -d '{"jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": {...}}' +``` + +**Agent receives:** + +``` +Authorization: Bearer +A2A-Version: 1.0 +x-trace-id: trace-xyz789 +x-upstream-token: user-abc +``` + +`x-debug` is not on the allowlist, and `x-portkey-api-key` is protected, so neither is forwarded. + + +Forwarded headers apply to requests proxied to the agent. They are not sent when Portkey fetches the agent card. + + +--- + +## Related + +| Topic | Description | +|-------|-------------| +| [Agent Registry](/product/agent-gateway/registry) | Manage agent integrations | +| [MCP header forwarding](/product/mcp-gateway/authentication/forwarding-headers) | The same feature for MCP servers | + + +import PrismaAirsCta from "/snippets/prisma-airs-cta.mdx"; + + diff --git a/product/agent-gateway/registry.mdx b/product/agent-gateway/registry.mdx index 3b10eb1c7..66e4718bb 100644 --- a/product/agent-gateway/registry.mdx +++ b/product/agent-gateway/registry.mdx @@ -33,6 +33,9 @@ Once you have successfully registered your agent, you can do the following: Learn how virtual agent servers work and how to host your own. + + Pass headers from client requests through to your agents. + From 6d41e929cb14d9707ae0ca08bed9f1844a5fc6c8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 11 Nov 2026 03:28:52 +0000 Subject: [PATCH 2/2] docs(agent-gateway): add valid A2A SendMessage payload Co-authored-by: narengogi <47327611+narengogi@users.noreply.github.com> --- product/agent-gateway/forwarding-headers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product/agent-gateway/forwarding-headers.mdx b/product/agent-gateway/forwarding-headers.mdx index 8af57c882..b68cec509 100644 --- a/product/agent-gateway/forwarding-headers.mdx +++ b/product/agent-gateway/forwarding-headers.mdx @@ -140,7 +140,7 @@ curl https://agents.portkey.ai/v1/agent/my-agent/a2a/jsonrpc \ -H 'x-trace-id: trace-xyz789' \ -H 'x-user-token: user-abc' \ -H 'x-debug: 1' \ - -d '{"jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": {...}}' + -d '{"jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": {"message": {"role": "user", "messageId": "msg-001", "parts": [{"text": "Hello, agent!"}]}}}' ``` **Agent receives:**