What this example shows
A BPMN-flavored workflow that documents how three specialized agents and a human reviewer cooperate to triage incoming orders. The diagram makes the routing logic, the fall-back to humans, the approval gate, and the terminate path explicit - so a reader can audit the system’s behavior without reading every prompt.
When to use it
When you operate a multi-agent system and need an honest picture of how the agents actually decide. Diagrams like this are useful for design review (does every input have a defined output?), for incident response (where did the order get stuck?), for onboarding new contributors (which agent does what?), and for compliance review (where does a human have to approve?).
What the agent does
A meta-agent reads the orchestration runtime’s configuration - the agent registry, the routing rules, the gateway conditions, the human-in-the-loop hooks - and translates them into a workflow scene. Each agent becomes a workflow.task. Gateways become workflow.gateway diamonds with the routing condition as the label. Human review steps stay visible as separate tasks because they’re behaviourally distinct from agent steps.
When the orchestration config changes, the same agent applies incremental updates: a new agent appears as a new task; a routing rule change appears as a relabeled gateway edge; deprecated agents disappear with a deleteElement operation.
What the output includes
- A start event (
workflow.messageStart), end event (workflow.messageEnd), and an explicit terminate path (workflow.terminate) for rejected orders. - Three agent tasks (Classifier, Fast-path, Complex-case) plus one human task - the diagram makes the human-in-the-loop step visible by design.
- Two gateway diamonds: one for routing simple vs complex orders, one for the human approval gate.
- A
workflow.subprocessfor “Execute order” - the actual fulfillment is delegated to a different diagram, kept out of this view. - BPMN-correct edge styling: solid sequence-flow lines with triangle arrowheads, gateway labels external to the diamond.
Rendered diagram
Drawn by Zindex from the scene below with POST /v1/diagrams/preview.
Open it in the Playground to swap themes (clean / dark / blueprint / sketch),
or add format: "png" to the same request for a PNG.
Scene JSON
Raw
The DSP scene the diagram above is drawn from. Open it in the
Playground, or send it as scene to
POST /v1/diagrams/preview to draw it yourself.
{
"schemaVersion": "0.1",
"diagramFamily": "workflow",
"scene": {
"id": "multi-agent-workflow",
"title": "Multi-agent Order Triage",
"brief": "How an order is triaged: a classifier routes it to a fast-path or complex-case agent; a human approves complex ones.\nBPMN: a task for each agent and for the human reviewer, an exclusive gateway for each decision with its outcomes as edge labels. Keep one start and two ends, Order complete and Rejected.",
"units": "px",
"canvas": {
"width": 1300,
"height": 420
}
},
"layoutStrategy": {
"direction": "LR",
"nodeSpacing": 35,
"rankSpacing": 80
},
"elements": [
{
"id": "msgStart",
"kind": "node",
"nodeType": "workflow.messageStart",
"shape": "ellipse",
"label": "Order received"
},
{
"id": "classifier",
"kind": "node",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Classifier agent"
},
{
"id": "decRoute",
"kind": "node",
"nodeType": "workflow.gateway",
"shape": "diamond",
"label": "Route?"
},
{
"id": "fast",
"kind": "node",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Fast-path agent"
},
{
"id": "complex",
"kind": "node",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Complex-case agent"
},
{
"id": "human",
"kind": "node",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Human reviewer"
},
{
"id": "decReview",
"kind": "node",
"nodeType": "workflow.gateway",
"shape": "diamond",
"label": "Approved?"
},
{
"id": "exec",
"kind": "node",
"nodeType": "workflow.subprocess",
"shape": "roundedRect",
"label": "Execute order"
},
{
"id": "notify",
"kind": "node",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Notify customer"
},
{
"id": "msgEnd",
"kind": "node",
"nodeType": "workflow.messageEnd",
"shape": "ellipse",
"label": "Order complete"
},
{
"id": "rejected",
"kind": "node",
"nodeType": "workflow.terminate",
"shape": "ellipse",
"label": "Rejected"
},
{
"id": "e1",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "msgStart"
},
"to": {
"elementId": "classifier"
},
"router": "orthogonal"
},
{
"id": "e2",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "classifier"
},
"to": {
"elementId": "decRoute"
},
"router": "orthogonal"
},
{
"id": "e3",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "decRoute"
},
"to": {
"elementId": "fast"
},
"router": "orthogonal",
"label": "simple"
},
{
"id": "e4",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "decRoute"
},
"to": {
"elementId": "complex"
},
"router": "orthogonal",
"label": "complex"
},
{
"id": "e5",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "complex"
},
"to": {
"elementId": "human"
},
"router": "orthogonal",
"label": "needs review"
},
{
"id": "e6",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "human"
},
"to": {
"elementId": "decReview"
},
"router": "orthogonal"
},
{
"id": "e7",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "decReview"
},
"to": {
"elementId": "rejected"
},
"router": "orthogonal",
"label": "no"
},
{
"id": "e8",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "decReview"
},
"to": {
"elementId": "exec"
},
"router": "orthogonal",
"label": "yes"
},
{
"id": "e9",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "fast"
},
"to": {
"elementId": "exec"
},
"router": "orthogonal"
},
{
"id": "e10",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "exec"
},
"to": {
"elementId": "notify"
},
"router": "orthogonal"
},
{
"id": "e11",
"kind": "edge",
"edgeType": "workflow.sequenceFlow",
"from": {
"elementId": "notify"
},
"to": {
"elementId": "msgEnd"
},
"router": "orthogonal"
}
]
} Agent workflow
Document a multi-agent triage workflow as an executable BPMN-style diagram. The diagram is generated from the agent-orchestration configuration (declarative - typically a YAML file describing classifiers, tools, gateways, and human-in-the-loop checkpoints) and is patched with typed operations when the orchestration changes.
Inputs
- Agent orchestration configuration file (e.g. agents/triage.yaml describing the classifier, downstream agents, gateway conditions, and human-review steps)
- The diagram's Zindex ID or key
- A Zindex API key, or an MCP client signed in to Zindex
Outputs
- A new revision of the diagram with one workflow node per orchestration step (start event, classifier task, gateways, downstream agents, human-reviewer task, terminate events)
- Rendered BPMN-style SVG suitable for embedding in onboarding docs and runbooks
- Revision history showing how the orchestration policy has evolved (added a fast-path gateway, raised the auto-approve threshold, added human review for complex cases)
- 01
Read the diagram
Workflow diagrams are long-lived. Read the current outline before deriving anything new: its first line gives the revision you will edit against, and each line after it gives an element's ID, node type and label, or a flow with its condition label.
- 02
Parse the orchestration configuration
Read agents/triage.yaml. Each entry describes one orchestration step: task type (
classifier,agent,human-review,gateway,terminate), inputs, outputs, gateway conditions. The YAML is structured precisely so that one entry maps to one workflow element. - 03
Compute the operation diff
For each orchestration step, ensure a node exists with the right
nodeType:workflow.messageStartfor the entrypoint,workflow.taskfor tasks,workflow.gateway(or one of the gateway* variants) for branching points,workflow.terminatefor terminal failure paths,workflow.messageEndfor the success completion. For each transition, ensure an edge exists withedgeType: workflow.sequenceFlowand a label for any condition (e.g. 'simple', 'complex', 'needs review'). - 04
Save the changes as one edit
One
diagram_editwithbaseRevisionset to the revision you read and amessagethat describes the policy change: 'add fast-path gateway: simple cases skip human review' is meaningful months later, where 'orchestration update' is not. The edit is all or nothing: if an operation has errors, it returnsVALIDATION_FAILEDand saves nothing. - 05
Fix what the warnings report
The edit's
warningslist the workflow rules the new revision breaks and what drawing it noticed, each with acode, theelementwhen there is one, and a one-linefix. A gateway with fewer than two outgoing flows returnsFAMILY_WORKFLOW_DECISION_FEW_OUTPUTS, and a diagram without a start or end event returnsFAMILY_WORKFLOW_NO_STARTorFAMILY_WORKFLOW_NO_END. When the orchestration YAML itself causes one, the YAML is malformed: report it to a human instead of drawing around it. - 06
Render the workflow diagram
Get SVG and PNG links to the new revision; they work without a key for 7 days. The hierarchical LR layout naturally separates the start event, branching gateways, parallel paths, and terminate events - readable left-to-right as a process. Download the SVG for the agent runbook so on-call engineers can see what the orchestration is supposed to do without reading YAML.
- 07
Publish the diagram to the agent runbook
Drop the rendered SVG into the runbook directory. When the agent system pages on-call (because a gateway threshold was crossed or human review queue is backed up), the runbook now includes the canonical orchestration diagram pinned to the deployed revision.
MCP recipe
For agents using Model Context Protocol. The tool sequence below matches the workflow steps; copy the prompt as a system message.
Tool sequence
- 01
diagram_getRead the diagram - 02
diagram_editSave the changes as one edit - 03
diagram_renderRender the workflow diagram
Unique tools used: diagram_get, diagram_edit, diagram_render.
Copyable agent prompt
Drop this verbatim into a system prompt for an MCP-connected agent.
The Zindex MCP server at https://api.zindex.ai/mcp exposes
the tools the prompt references (connect a client),
and so does the npm package @zindexai/mcp, which forwards
to it.
You maintain the BPMN-style diagram of a multi-agent triage orchestration that the team keeps in Zindex, so on-call engineers, designers, and new hires can see what the system is supposed to do without reading the YAML. When the orchestration configuration changes, you change the diagram with typed edits, each with a message describing the policy change. Every revision is kept, so anyone can open the orchestration as it was designed on any date.
The diagram's Zindex ID is `${SCENE_ID}`; it already exists. Each agent orchestration has one diagram; revisions track policy changes ('add fast-path gateway', 'raise auto-approve threshold', 'add human review for complex cases').
Steps for each update (for example when `agents/triage.yaml` or its peers change):
1. Read `agents/triage.yaml` (or whatever orchestration configuration file the project uses). Each entry describes one workflow step: type (`classifier`, `agent`, `human-review`, `gateway`, `terminate`), inputs, outputs, gateway conditions. The YAML is structured intentionally so that one entry maps to one workflow element - do not parse free-text comments; rely on the structured fields.
2. Call `diagram_get({ id: "${SCENE_ID}" })` to read the current revision and elements. The outline's first line gives the revision; each line after it gives an element's ID, node type and label, or a flow (`id: from -> to "label"`).
3. For each orchestration step, compute the corresponding workflow element. Map the step type to a `nodeType`: `workflow.messageStart` for the message-driven entrypoint, `workflow.task` for synchronous tasks, `workflow.subprocess` for calls into nested workflows, `workflow.gateway` (or one of the typed gateway variants when applicable) for branching, `workflow.terminate` for terminal failure paths, `workflow.messageEnd` for successful completion. Use the step's stable identifier (the YAML key) as the element id - never re-derive ids; renames must produce `updateNode`, not delete-and-create.
4. For each transition between steps, compute the corresponding edge with `edgeType: workflow.sequenceFlow`. Label the edge with any gateway condition ('simple', 'complex', 'yes', 'no'). Use stable edge ids built from `e_${from_id}_${to_id}` so re-running doesn't churn the graph.
5. Diff what you parsed against the diagram. New steps → `createNode`. Removed steps → `deleteElement`. Changed types → `updateNode` (the type might change when the policy decides a former task should become a gateway). Changed conditions → `updateEdge`.
6. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision, message, ops })` with one batch, `baseRevision` set to the revision you read. The edit is all or nothing. The `message` should describe the policy change: 'add fast-path gateway: simple cases skip human review' is meaningful months later in the revision history, where 'orchestration update' is not. If the call returns `REVISION_CONFLICT`, the diagram changed after you read it: the error lists what changed, so re-plan against the new revision.
7. An edit with errors returns `VALIDATION_FAILED` and saves nothing. A saved edit returns `warnings`: the workflow rules the new revision breaks and what drawing it noticed, each with a `code`, the `element` when there is one, and a one-line `fix`. A gateway with fewer than two outgoing flows returns `FAMILY_WORKFLOW_DECISION_FEW_OUTPUTS`, and a diagram without a start or end event returns `FAMILY_WORKFLOW_NO_START` or `FAMILY_WORKFLOW_NO_END`. If those come from the orchestration YAML itself, the YAML is malformed and a human should review it.
8. Call `diagram_render({ id: "${SCENE_ID}" })`. It returns SVG and PNG links to the new revision, valid for 7 days. Download the SVG and commit it next to the agent runbook (`docs/runbooks/triage.md`). When the orchestration pages on-call (a gateway threshold crossed, a human-review queue backed up), the runbook now includes the canonical diagram pinned to the deployed revision - so the responder sees what the system was *supposed* to do, then compares to what actually happened.
Hard rules: never hand-edit the rendered SVG; the rendered file is a throwaway projection of the saved diagram. Never recreate the diagram from scratch; always patch with stable ids - orchestration policy evolves over many small changes, and stable ids are what make the revision history a meaningful policy changelog. If an edit fails, or warns about a workflow rule, report the problem (`code`, `element`, `fix`) to the person who asked; do not silently work around BPMN semantic violations.
HTTP API recipe
For agents/devs not using MCP. Send
Authorization: Bearer $ZINDEX_API_KEY on every call
except POST /v1/diagrams/validate and
POST /v1/diagrams/preview, which need no key. In the
paths, ${SCENE_ID} is the diagram's ID, or the
key you gave it in diagram_create. Full
reference: REST API, OpenAPI spec.
- 01
GET/v1/diagrams/${SCENE_ID}Workflow diagrams are long-lived. Read the current outline before deriving anything new: its first line gives the revision you will edit against, and each line after it gives an element's ID, node type and label, or a flow with its condition label.
- 02
POST/v1/diagrams/${SCENE_ID}/revisionsOne
diagram_editwithbaseRevisionset to the revision you read and amessagethat describes the policy change: 'add fast-path gateway: simple cases skip human review' is meaningful months later, where 'orchestration update' is not. The edit is all or nothing: if an operation has errors, it returnsVALIDATION_FAILEDand saves nothing. - 03
GET/v1/diagrams/${SCENE_ID}/renderGet SVG and PNG links to the new revision; they work without a key for 7 days. The hierarchical LR layout naturally separates the start event, branching gateways, parallel paths, and terminate events - readable left-to-right as a process. Download the SVG for the agent runbook so on-call engineers can see what the orchestration is supposed to do without reading YAML.
Operations
Raw The typed operations that build this diagram from empty. Save an
empty diagram with diagram_create, then send the
envelope's baseRevision, message and
ops to diagram_edit, or
POST /v1/diagrams/{id}/revisions. Each op
carries a stable id so subsequent runs can update the
same elements instead of regenerating.
{
"schemaVersion": "0.1",
"sceneId": "multi-agent-workflow",
"baseRevision": 1,
"message": "Initial multi-agent triage workflow: classifier, fast/complex/human paths",
"ops": [
{
"op": "createNode",
"id": "msgStart",
"nodeType": "workflow.messageStart",
"shape": "ellipse",
"label": "Order received"
},
{
"op": "createNode",
"id": "classifier",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Classifier agent"
},
{
"op": "createNode",
"id": "decRoute",
"nodeType": "workflow.gateway",
"shape": "diamond",
"label": "Route?"
},
{
"op": "createNode",
"id": "fast",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Fast-path agent"
},
{
"op": "createNode",
"id": "complex",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Complex-case agent"
},
{
"op": "createNode",
"id": "human",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Human reviewer"
},
{
"op": "createNode",
"id": "decReview",
"nodeType": "workflow.gateway",
"shape": "diamond",
"label": "Approved?"
},
{
"op": "createNode",
"id": "exec",
"nodeType": "workflow.subprocess",
"shape": "roundedRect",
"label": "Execute order"
},
{
"op": "createNode",
"id": "notify",
"nodeType": "workflow.task",
"shape": "roundedRect",
"label": "Notify customer"
},
{
"op": "createNode",
"id": "msgEnd",
"nodeType": "workflow.messageEnd",
"shape": "ellipse",
"label": "Order complete"
},
{
"op": "createNode",
"id": "rejected",
"nodeType": "workflow.terminate",
"shape": "ellipse",
"label": "Rejected"
},
{
"op": "createEdge",
"id": "e1",
"from": {
"elementId": "msgStart"
},
"to": {
"elementId": "classifier"
},
"edgeType": "workflow.sequenceFlow",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e2",
"from": {
"elementId": "classifier"
},
"to": {
"elementId": "decRoute"
},
"edgeType": "workflow.sequenceFlow",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e3",
"from": {
"elementId": "decRoute"
},
"to": {
"elementId": "fast"
},
"edgeType": "workflow.sequenceFlow",
"label": "simple",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e4",
"from": {
"elementId": "decRoute"
},
"to": {
"elementId": "complex"
},
"edgeType": "workflow.sequenceFlow",
"label": "complex",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e5",
"from": {
"elementId": "complex"
},
"to": {
"elementId": "human"
},
"edgeType": "workflow.sequenceFlow",
"label": "needs review",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e6",
"from": {
"elementId": "human"
},
"to": {
"elementId": "decReview"
},
"edgeType": "workflow.sequenceFlow",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e7",
"from": {
"elementId": "decReview"
},
"to": {
"elementId": "rejected"
},
"edgeType": "workflow.sequenceFlow",
"label": "no",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e8",
"from": {
"elementId": "decReview"
},
"to": {
"elementId": "exec"
},
"edgeType": "workflow.sequenceFlow",
"label": "yes",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e9",
"from": {
"elementId": "fast"
},
"to": {
"elementId": "exec"
},
"edgeType": "workflow.sequenceFlow",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e10",
"from": {
"elementId": "exec"
},
"to": {
"elementId": "notify"
},
"edgeType": "workflow.sequenceFlow",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e11",
"from": {
"elementId": "notify"
},
"to": {
"elementId": "msgEnd"
},
"edgeType": "workflow.sequenceFlow",
"router": "orthogonal"
}
]
} Validation
Valid
Captured response from POST /v1/diagrams/validate, the
check diagram_validate runs. It checks the scene and
draws it. Every code it can return is in the validation rules.
- 0 errors
- 0 warnings
The scene validates with no errors or warnings.
Each entry has a code, the element it
concerns when there is one, and a one-line fix.
diagram_create and diagram_edit save
nothing when there are errors and return
VALIDATION_FAILED; warnings don't block a save. Both
return the same warnings for the revision they save, so an agent
reads them from the write itself.
Revision diff
Raw
What changed between two revisions of the diagram, as
diagram_history returns it with compare.
Every revision is kept, so any two can be compared, by revision
number or by date.
Scenario
The orchestration diagram's first save. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so every event, task, gateway and flow is added. A later policy change, such as a new escalation path, compares the same way and names only the steps and flows it added, changed or removed.
- Revision 1 → 2
- +22 added
- -0 removed
- ~0 changed
- scene fields changed: canvas
+ Added
msgStartclassifierdecRoutefastcomplexhumandecReviewexecnotifymsgEndrejectede1e2e3e4e5e6e7e8e9e10e11
Raw compare response
{
"id": "dgm_e6DeHY3uEpuc",
"from": 1,
"to": 2,
"added": [
"msgStart",
"classifier",
"decRoute",
"fast",
"complex",
"human",
"decReview",
"exec",
"notify",
"msgEnd",
"rejected",
"e1",
"e2",
"e3",
"e4",
"e5",
"e6",
"e7",
"e8",
"e9",
"e10",
"e11"
],
"changed": [],
"removed": [],
"scene": [
"canvas"
],
"scenario": "The orchestration diagram's first save. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so every event, task, gateway and flow is added. A later policy change, such as a new escalation path, compares the same way and names only the steps and flows it added, changed or removed."
}
To compare two versions of your own diagram, call
diagram_history with compare: { from, to },
or GET /v1/diagrams/{id}/compare with
from and to, giving revision numbers or
dates. With an API key,
GET /v1/images/{id}@{to}.svg?from={from}
draws the later version with what changed colored.
Agent resources
Machine-readable versions of this example. Agents should fetch these rather than scrape the rendered HTML.
-
multi-agent-workflow.scene.jsonCanonical DSP scene Open -
multi-agent-workflow.ops.jsonTyped-operation envelope that builds the scene Open -
multi-agent-workflow.workflow.jsonStructured agent workflow (goal, inputs, outputs, steps) Open -
multi-agent-workflow.diff.jsonSamplediagram_historycompare response Open -
multi-agent-workflow.svgRendered diagram Open -
multi-agent-workflow.mdAgent-readable markdown summary Open -
/examples/index.jsonManifest of all examples (cross-linked) Open