Multi-Agent Traces

Multi-Agent Traces

When several agents collaborate in one run, Retrace records which agent produced each span, draws the agent topology, and runs detectors built for the failure modes unique to multi-agent systems. Single-agent traces are completely unaffected — these fields are optional and the topology graph only appears when a trace has 2 or more distinct agents.

Every span can carry three optional fields:

Instrumentation

Python

Wrap a sub-agent's work in retrace.agent(...); every span recorded inside it (including auto-instrumented LLM calls) inherits the agent fields. Nesting expresses delegation — the inner agent's parent_agent_id is set to the outer one automatically.

import retrace

with retrace.agent("planner", role="Planner"):
    plan = make_plan(task)
    with retrace.agent("researcher", role="Researcher"):
        facts = research(plan)        # parent_agent_id = "planner"

TypeScript

withAgent uses AsyncLocalStorage, so concurrent agents never clobber each other's context.

import { withAgent } from "retrace-sdk";

await withAgent({ id: "planner", role: "Planner" }, async () => {
  const plan = await makePlan(task);
  await withAgent({ id: "researcher", role: "Researcher" }, async () => {
    await research(plan);             // parentAgentId = "planner"
  });
});

Or set the fields on a single span directly: spanBuilder.setAgent({ id, parentId, role }).

Frameworks

• LangGraph — use the node name as the agent_id.
• CrewAI — use the agent's role as the agent_id and role.

OpenTelemetry

Retrace maps the OTel GenAI agent semantic-convention attributes automatically:

The same fields are accepted identically over HTTP batch ingest, the WebSocket stream, and OTel — instrument once, send anywhere.

Topology view

Open any multi-agent trace and you'll see the Agent topology graph above the detections panel: each agent is a node (sized by span count), and arrows are control hand-offs with thickness proportional to frequency. Single-agent traces don't render the graph at all.

Detectors

The two AI-powered detectors require the Inter-agent detectors feature (Pro and above) and only run on multi-agent traces. The ping-pong loop detector and the topology view are available on every plan. All three surface as standard detections in the trace's detections panel and the Insights → Failure Taxonomy breakdown.