Step tree
Show agent progress as nested steps, where anything a step made opens right from that step.
The problem
An agent doing real work runs things in parallel, like three questions at once, each writing and running its own query. Stream that as flat “thinking” lines and you get an unreadable interleave.
Worse, the work disappears. The queries it ran are gone the moment the answer shows up, so you can’t check how it got there.
What I concluded
Make every unit of work a step. A step’s lines, its child steps, and anything it made all nest under it. Each step opens as running and closes as done or failed, with a one-line outcome.
async function step(ctx, label, work, opts = {}) {
const id = randomUUID();
const mark = (status, text) =>
ctx.inform(text, { stepId: id, status });
mark("running", label);
try {
const result = await work(within(ctx, id)); // children nest
mark("done", opts.outcome?.(result) ?? label);
return result;
} catch (err) {
mark("failed", err.message || label);
throw err;
}
}
Rendered, parallel branches stay separate:
✓ Checking 3 questions 4.1s
✓ Which customers ordered this month? 12 rows [open]
✓ Which of those asked for a refund? 3 rows [open]
✗ Who owns them? no owner field
Inspectables
A step can attach a payload, like the query it ran. It renders like any other payload of its kind, so a query opens like a query card. But it never enters the model’s context or the chat history. It’s there so the person can check the work, not for the model to reread.
Rules
- One step per unit of work. Nesting comes from where a step runs, not from bookkeeping.
- Every step closes. Done or failed, with a short outcome and how long it took.
- Failures stay in place. A failed branch shows its reason without hiding its siblings.
- Inspectables are for people. They stay out of the model’s context.
- Additive on the wire. A client that ignores step ids still gets plain thinking lines.
What you get
Progress reads like the work, parallel branches stay legible, and every query the agent ran opens from the step that ran it. Checking the answer becomes a click instead of a guess.
Related: Agent loop, Event stream, Checkable output