Represent hierarchical agent workflows
Model runs, nested and concurrent steps, retries, tools, and interactions without turning internal agent traffic into announcement noise.
Maintained by Bhavesh Chowdhury
Preserve explicit hierarchy
runId and stepId identify logical work. runInstanceId and
stepInstanceId identify attempts. Parent run and step IDs preserve nesting
only when the source exposes it. Responses, tools, approvals, and interactions
can carry the same workflow context without becoming steps themselves.
runtime.dispatch({
type: "step.started",
runId: "report",
runInstanceId: "run-1",
stepId: "sources",
stepInstanceId: "sources-2",
parentStepId: "research",
label: "Collect sources",
});Concurrent siblings keep separate IDs. Completing or failing one does not complete or cancel another. A successful parent completion is rejected while a known child remains active.
Keep routine workflow traffic quiet
The balanced policy announces terminal run summaries and identified steps only after they become long-running. Nested steps and progress remain quiet by default. Step failures use the configured error channel, while approval and input requests retain their existing priority. When a completed response boundary was already announced and a run has no identified step summary, its generic completion is silent instead of repeating the same boundary.
Use policy.workflows to choose run boundary verbosity, silent, long-running,
or all step boundaries, the long-running threshold, progress announcements,
and whether nested steps may speak.
Replace attempts without leaking stale work
step.retrying and run.retrying create explicit attempt boundaries. The
runtime cancels announcements owned by the replaced attempt and its descendants
while preserving siblings. Events carrying an older instance ID are diagnosed
as stale and do not produce output.
When a source exposes only a step name, omit stepId. The runtime emits an
ephemeral partial-identity diagnostic, but cannot create a step snapshot,
announcement, or run count from that evidence. It never treats display text,
array position, or timing as identity.