Multi-agent systems are hard to debug because each agent logs its own story. A planner hands work to a researcher, which calls a writer, and when the final answer is wrong you’re left stitching three logs together by timestamp.
One run, one trace
Sigil propagates a trace context through every handoff. Pass the parent run when you call another agent and every span lands in the same tree.
ts
const plan = await planner.run(input) const notes = await researcher.run(plan, { parent: plan.runId, })
Reading the waterfall
The trace view shows each agent as a lane. Handoffs appear as arrows between lanes, so you can see exactly what one agent passed to the next.
Wide gaps between spans usually mean a slow tool or a queue.
Repeated spans in one lane point to retries or loops.
A handoff with a tiny payload is often where context got lost.
Add your own spans
Wrap any function in sigil.span() to add it to the tree. We recommend it for retrieval, ranking and anything that talks to your own database.
Keep payloads small
Spans store inputs and outputs by default. For large documents, store a hash and a preview instead, using the redact option.
