Skip to content

Cross-Fleet Tracing Contract ​

This document specifies the HTTP header contract protoVoice uses to stitch Langfuse traces across the protoLabs agent fleet. Workstacean, ava, and any future fleet agents implement against this so a full user-turn trace spans every service it touches, not just ours.

TL;DR ​

On every outbound request to another agent, protoVoice attaches two headers:

HeaderRequiredShapePurpose
Langfuse-Session-Idyes32-char hexThe caller's Langfuse session (= our WebRTC session)
Langfuse-Trace-Idyes32-char hexThe current user-turn trace ID
Langfuse-Parent-Observation-Idoptional32-char hexIf present, the caller wants your spans nested under this specific observation (span) instead of directly under the trace.

Receivers must honor them: instead of creating a fresh trace, open a new root span attached to the caller's trace via langfuse.start_observation(as_type="span", trace_context=TraceContext(trace_id=trace_id)) (Langfuse v4 SDK) and tag it with the session via span._otel_span.set_attribute(LangfuseOtelSpanAttributes.TRACE_SESSION_ID, session_id). All spans you open for this request then nest inside the caller's trace.

If the headers are absent, treat the call as an independent trace — normal Langfuse behaviour.

When protoVoice attaches these headers ​

Every outbound HTTP call made in the context of a live user turn:

  • A2A message/stream / message/send — a2a/client.py::dispatch_message_stream and dispatch_message.
  • OpenAI-compat /v1/chat/completions to a delegate — agent/delegates.py::_dispatch_openai.
  • Any future fleet-to-fleet RPC that runs inside a user-turn trace.

The values come from the _ACTIVE_TRACER.get_current_trace() in agent/tracing.py. If the TurnTracer has no live trace (pre-session or post-session), the headers are omitted.

What receivers must do ​

1. Accept the headers ​

python
# Python (example; any language works)
trace_id = request.headers.get("Langfuse-Trace-Id")
session_id = request.headers.get("Langfuse-Session-Id")
parent_id = request.headers.get("Langfuse-Parent-Observation-Id")

2. Continue, don't create ​

python
from langfuse import Langfuse, LangfuseOtelSpanAttributes as A
from langfuse.types import TraceContext

langfuse = Langfuse(...)

def _stamp(span, *, session_id=None, user_id=None):
    """Tag the OTEL span with trace-level session/user so Langfuse aggregations work."""
    if session_id: span._otel_span.set_attribute(A.TRACE_SESSION_ID, session_id)
    if user_id:    span._otel_span.set_attribute(A.TRACE_USER_ID, user_id)

if trace_id and session_id:
    # Re-attach: a new root span linked to the caller's existing trace.
    root = langfuse.start_observation(
        name="ava.handle_request",
        as_type="span",
        trace_context=TraceContext(trace_id=trace_id, parent_span_id=parent_id),
    )
    _stamp(root, session_id=session_id)
    # New spans for this request nest under the caller's trace; stamp each
    # so aggregations by session_id include them too.
    child = root.start_observation(name="ava.handle_request.llm", as_type="generation")
    _stamp(child, session_id=session_id)
else:
    root = langfuse.start_observation(name="ava.standalone_request", as_type="span")

Why the direct _otel_span.set_attribute(...) instead of Langfuse's propagate_attributes(...) context manager: propagate_attributes only tags spans created inside an active context. If your receiver creates child spans across async task boundaries (observer callbacks, background workers), the OTEL context doesn't follow automatically — stamping each span at creation time is robust regardless.

3. Propagate ​

If your agent itself calls further downstream agents (chained delegation), continue propagating the same headers. The trace fans out as a single tree.

4. Flush ​

Call langfuse.flush() before returning the HTTP response so the caller sees your spans in Langfuse within a second or two, not eventually.

Why session + trace, not just trace ​

Sessions are Langfuse's unit for "one conversation" — they're what users filter by in the UI. Each WebRTC session is one Langfuse session; every user turn in that session is a trace under it. Including session_id lets the receiver display your spans under the correct conversation in their view even if they also happen to aggregate by session elsewhere.

Security ​

These headers are identifiers, not secrets. Forging a Langfuse-Trace-Id only lets you append spans to someone else's trace in the Langfuse UI — it doesn't grant access to anything. There's no authentication implied; agent-to-agent authentication happens separately (API keys, bearer tokens, the existing A2A auth model).

Don't log the full header values in high-volume places — they're noisy but otherwise benign.

Versioning ​

This contract is v1. Future changes (e.g. W3C traceparent interop) bump the version via an additional Langfuse-Contract-Version: 2 header; receivers fall back to v1 behaviour when unset.

protoVoice is on the Langfuse v4 Python SDK. The header contract itself is SDK-agnostic — receivers on v2 or v3 can still read Langfuse-Trace-Id / Langfuse-Session-Id and attach spans via whatever API their SDK offers — but the "Continue, don't create" example above is written against v4.

Implementation status ​

  • protoVoice — writing these headers: K24 (this release). Reading them (for inbound requests via /a2a, future /api/*): K24 receive side.
  • workstacean — ava's side: workstacean team implements against this doc.
  • Any future fleet agent — same.

Part of the protoLabs autonomous development studio.