From 13f7d85b00c375080382efdb860c0d84a1b66e60 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 conversation-scoped LLM headers Co-authored-by: openhands --- sdk/guides/observability.mdx | 37 ++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/sdk/guides/observability.mdx b/sdk/guides/observability.mdx index 3d82289c..f0a9e351 100644 --- a/sdk/guides/observability.mdx +++ b/sdk/guides/observability.mdx @@ -141,6 +141,43 @@ 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 +by a conversation: + +```python icon="python" wrap +conversation = Conversation( + agent=agent, + workspace=workspace, + llm_extra_headers={"X-Request-ID": request_id}, +) +conversation.send_message("Investigate the failing deployment") +conversation.run() +``` + +The same option works with local and remote conversations and with synchronous or +asynchronous runs. For direct Agent Server clients, include it in the conversation +creation request alongside the required agent and workspace fields: + +```json wrap +{ + "llm_extra_headers": { + "X-Request-ID": "request-123" + } +} +``` + +The headers remain active for every run of the live conversation, including retries, +condensation, sub-agents, and agent hooks. They override static `LLM.extra_headers` +with the same name, while SDK-managed headers are preserved. The headers are not +persisted, so a new conversation or a server restart requires supplying them again. + + +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