From 852609aa554424f257c5ef810faea1e6efa20ad4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D0=BB=D0=B5=D0=BA=D1=81=D0=B0=D0=BD=D0=B4=D1=80=20?= =?UTF-8?q?=D0=91=D0=BE=D0=B6=D0=BD=D1=8E=D0=BA?= Date: Fri, 10 Jul 2026 09:27:04 +0200 Subject: [PATCH] docs(sdk): document run-scoped LLM headers --- sdk/guides/observability.mdx | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/sdk/guides/observability.mdx b/sdk/guides/observability.mdx index 3386e55e..86583415 100644 --- a/sdk/guides/observability.mdx +++ b/sdk/guides/observability.mdx @@ -140,6 +140,37 @@ Each conversation gets its own session ID (the conversation UUID), allowing you In `tool.execute`, the tool calls are traced individually, such as `bash`, `file_editor`, or `task_tracker`. +### Correlate LLM Requests With Application Requests + +Pass `llm_extra_headers` to attach application metadata to every LLM call made +during one conversation run: + +```python icon="python" wrap +conversation.send_message("Investigate the failing deployment") +conversation.run( + llm_extra_headers={"X-Request-ID": request_id}, +) +``` + +The same option works with `await conversation.arun(...)` and with +`RemoteConversation`. For direct Agent Server clients, include it in the run request: + +```bash icon="terminal" wrap +curl -X POST "${AGENT_SERVER_URL}/api/conversations/${CONVERSATION_ID}/run" \ + -H "Content-Type: application/json" \ + -d '{"llm_extra_headers":{"X-Request-ID":"request-123"}}' +``` + +The headers apply to the main agent, retries, condensation, and sub-agent LLM calls +started by that run. They override static `LLM.extra_headers` with the same name, but +SDK-managed headers are preserved. Run-scoped headers are not persisted and do not +affect later runs. + + +Header values are sent to the configured LLM provider. Treat them as sensitive and +avoid logging them or placing secrets in correlation headers. + + ## Configuration Reference ### Environment Variables