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