How do Helicone's session headers group an agent's many calls into one trace?

## Why a flat log is not enough One prompt and one completion fits comfortably in a table row. An agent does not. A single user question can fan out into a planning call, several tool-argument calls, a retrieval step, a synthesis call and a self-check, possibly across multiple services. Logged flatly, those are unrelated rows that happen to share a timestamp range — you cannot tell which belong together, you cannot total the run's real cost, and you cannot replay the reasoning. Helicone's answer is a set of request headers that let the caller declare the structure the proxy cannot infer. ## The three headers - **`Helicone-Session-Id`** — the correlation key. Any requests sharing this value belong to the same session. Generate one identifier per run (a UUID is typical) at the entry point. - **`Helicone-Session-Name`** — a human label for the run, such as `support-agent` or `weekly-report`. Sessions are otherwise identified by an opaque id, and a name is what makes them findable and comparable. - **`Helicone-Session-Path`** — the position of this call in the run, expressed as a slash-delimited path. A top-level step might be `/plan`; a call made while executing that step might be `/plan/search`. The nesting implied by the path is what turns a list into a tree. All three are ordinary request headers, so they are set per call — typically as extra headers on the individual request, not as client defaults, since the path (and often the id) changes between calls. ## Threading them through the code This is where implementations go wrong. There is no ambient context: if a header is not on the request, the call is not in the session. In practice that means: - Create the session id once, at the boundary where the run begins, and put it somewhere the whole run can read — a request-scoped context object, a contextvar, an explicit parameter. - Maintain a current path as you descend, appending a segment when you enter a sub-step, so calls made inside that step carry the deeper path. - Propagate across process boundaries yourself. If a step is handed to a worker or another service, the session id must travel with the job payload or it will start its own orphan trace. - Cover retries and background work. A retried call that loses the header creates a row that looks unrelated to the run it belongs to. ## What you get With the headers in place, a session view gives you the things flat rows cannot: - **Whole-run cost.** The number that matters for an agent is cost per completed task, not per call — and it is often startling the first time you see it, because the planning and tool-argument calls outnumber the visible ones. - **Ordered replay.** Walk the calls in sequence to see where a run went wrong: a bad plan, a tool that returned junk, a synthesis step that ignored its context. - **Shape comparison.** Two runs of the same agent that differ wildly in call count usually indicate a loop that is not terminating, which is far easier to see as a tree than as rows. - **Latency decomposition.** Which step dominates wall-clock time for the user. ## Sessions versus properties versus user id These three metadata mechanisms are complementary and get confused: - A **session** groups the calls of one run. High cardinality is expected and correct here — one value per run. - A **custom property** (`Helicone-Property-*`) is a low-cardinality descriptive dimension for aggregation: feature, environment, version. - **`Helicone-User-Id`** identifies who the run was for, and is what per-user cost views key on. A well-instrumented agent call carries all three: a user id, a couple of properties, and the session trio. Reaching for a property when you meant a session is the common mistake, and it produces a dimension with one member per run that no dashboard can use. ## Mode notes Grouping is a property of the log record rather than something interception provides, so sessions work under async logging too — the identifiers are part of the payload you send instead of headers on a proxied request. Either way the discipline is the same: the structure exists only because your code declared it, so treat session propagation as part of the agent's plumbing rather than an afterthought bolted on during an incident.