Multi-agent instrumentation

Multi-agent traces become useful when identity and handoffs survive export. Perseval tolerates missing roots, out-of-order spans, multiple roots, and cycles, but explicit topology is more precise.

orchestrator
├── planner
├── retriever
│   └── browser
├── executor
└── verifier

Use parent/child relationships for work that belongs to one execution branch. Use SpanLinks when a handoff, queue, fan-out, or verification relationship is real but is not ownership.

Add both when possible:

gen_ai.agent.id = release-verifier-1
agent.role = release_verifier

Several agents may share service.name. The role chip should answer “what responsibility did this span have here?” rather than repeat the service name.

Give every span accurate nanosecond start and end timestamps. Parallel search/docs or test/security branches then appear as overlapping timeline bars rather than a misleading sequence.

Do not fabricate parentage to make a tree look tidy. Perseval keeps multiple roots and unresolved parents visible, reparents late children when their parent arrives, and persists stable finalized topology.

Use a SpanLink from the receiving span to the span whose result or decision it consumes. A verifier that uses retriever evidence can link to the retriever span even when both have different parents.

Include bounded handoff metadata on the receiving span or link, such as:

agent.handoff = evidence
agent.role = verifier

In Full Trace → Inspector → Span, Perseval shows the preserved target trace ID, span ID, trace state, flags, attributes, and dropped-attribute count. Links are evidence; they do not merge nodes from different agents.

Use span events for time-local observations such as retry scheduling, tool exceptions, approvals, escalation, and verification results. Keep names stable and attributes bounded. Events and SpanLinks are retained in evidence packets without exposing externalized payload bodies.

Model each attempt as a span or an explicitly numbered call with agent.tool.attempt. A later success is not automatically compatible recovery: it should target the same operation and relevant state. For a mutating timeout, emit a separate verifying operation and state observation instead of marking the retry as safe by assumption.

1. Runs shows explicit session, build, and environment.
2. Full Trace → Tree shows each agent role and preserved roots.
3. Timeline shows intended concurrency without overlapping labels.
4. Inspector → Span shows the expected events and link count.
5. Compare keeps identities separate and aligns equivalent responsibilities.