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