# Multi-agent workflow diagram
> Visualise how multiple agents, tools, queues, and human review steps interact in an automated workflow. BPMN-style with start/end events, gateways, and intermediate signals.
## Metadata
- **Diagram family**: `workflow`
- **Source**: Agent configuration / orchestration runtime
- **Workflow types**: generate, update, validate, render
- **Audience**: developer, agent, platform
- **MCP tools**: `dsp_create_scene`, `dsp_apply_ops`, `dsp_validate_scene`, `dsp_render_scene`
- **HTTP endpoints**:
  - `POST /v1/scenes`
  - `POST /v1/scenes/:id/applyOps`
  - `POST /v1/scenes/:id/render`
---
---

## What this example shows

A BPMN-flavoured workflow that documents how three specialised 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 behaviour 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.

The same agent can re-run on every change to the orchestration config and apply incremental updates: a new agent appears as a new task; a routing rule change appears as a relabelled 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.subprocess` for "Execute order" - the actual fulfilment 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.
## 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 stays in sync as the orchestration evolves.
**Inputs**

- Agent orchestration configuration file (e.g. agents/triage.yaml describing the classifier, downstream agents, gateway conditions, and human-review steps)
- Existing Zindex scene id
- Zindex API key
**Outputs**

- Updated persisted scene 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)
**Steps**

1. **Fetch the persisted scene** - Workflow scenes are long-lived. Fetch the current revision before deriving anything new.
   _MCP: `dsp_get_scene` · HTTP: `GET /v1/scenes/${SCENE_ID}`_

2. **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.

3. **Compute the operation diff** - For each orchestration step, ensure a node exists with the right `nodeType`: `workflow.messageStart` for the entrypoint, `workflow.task` for tasks, `workflow.gateway` (or one of the gateway* variants) for branching points, `workflow.terminate` for terminal failure paths, `workflow.messageEnd` for the success completion. For each transition, ensure an edge exists with `edgeType: workflow.sequenceFlow` and a label for any condition (e.g. 'simple', 'complex', 'needs review').

4. **Apply the operation batch** - One applyOps batch with errorPolicy=allOrNothing. The revisionMessage should describe the policy change: 'add fast-path gateway: simple cases skip human review' is meaningful months later, where 'orchestration update' is not.
   _MCP: `dsp_apply_ops` · HTTP: `POST /v1/scenes/${SCENE_ID}/ops`_

5. **Validate the workflow scene** - Confirm BPMN semantics: every gateway has at least two outgoing edges, every messageStart has at least one outgoing edge, every messageEnd has at least one incoming edge. The platform validates these automatically against the workflow diagram family.
   _MCP: `dsp_validate_scene` · HTTP: `POST /v1/scenes/validate`_

6. **Render the workflow diagram** - Render to SVG. The hierarchical LR layout naturally separates the start event, branching gateways, parallel paths, and terminate events - readable left-to-right as a process. Embed the rendered SVG in the agent runbook so on-call engineers can see what the orchestration is supposed to do without reading YAML.
   _MCP: `dsp_render_scene` · HTTP: `POST /v1/scenes/${SCENE_ID}/render`_

7. **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.
## Agent prompt

Drop this into a system prompt for an MCP-connected agent.

```
You are an automated workflow-documentation agent. Your job is to keep a BPMN-style diagram of a multi-agent triage orchestration in sync with the orchestration configuration, so that on-call engineers, designers, and new hires always see what the system is supposed to do - independent of the YAML they would otherwise have to read.

The persisted Zindex scene id is `${SCENE_ID}`; it already exists. Each agent orchestration has one scene; revisions track policy changes ('add fast-path gateway', 'raise auto-approve threshold', 'add human review for complex cases'). Treat the scene as the canonical visual contract for the orchestration.

Workflow on every run (typically on every PR that touches `agents/triage.yaml` or its peers, plus a daily scheduled run as a safety net):

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 `dsp_get_scene({ sceneId: "${SCENE_ID}" })` to read the current revision and elements.

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 persisted scene. 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 `dsp_apply_ops` with one batch. `errorPolicy: "allOrNothing"`. The `revisionMessage` should describe the policy change: 'add fast-path gateway: simple cases skip human review' is meaningful months later in the audit trail, where 'orchestration update' is not.

7. Call `dsp_validate_scene`. Resolve workflow-family-specific issues: every gateway needs at least two outgoing edges, every messageStart needs at least one outgoing edge, every messageEnd needs at least one incoming edge. The platform validates these automatically against the `workflow` diagram family - if validation fails, the orchestration YAML is itself malformed and a human should review.

8. Call `dsp_render_scene({ format: "svg", theme: "clean" })`. Embed the rendered SVG in the agent runbook (`docs/runbooks/triage.md`) via a stable URL. 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 persisted scene. Never regenerate the scene 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 validation fails, surface the structured diagnostic (`code`, `path`, `message`) on the PR; do not silently work around BPMN semantic violations.
```
## Validation

Captured `POST /v1/scenes/validate` response: **valid** (0 diagnostics)

_Scene validates with no diagnostics._
## Resources
- **Canonical scene**: [/examples/multi-agent-workflow.scene.json](/examples/multi-agent-workflow.scene.json)
- **Operations envelope**: [/examples/multi-agent-workflow.ops.json](/examples/multi-agent-workflow.ops.json)
- **Workflow recipe**: [/examples/multi-agent-workflow.workflow.json](/examples/multi-agent-workflow.workflow.json)
- **Revision diff**: [/examples/multi-agent-workflow.diff.json](/examples/multi-agent-workflow.diff.json)
- **GitHub Actions workflow**: [/examples/multi-agent-workflow.github-actions.yml](/examples/multi-agent-workflow.github-actions.yml)
- **Rendered SVG**: [/examples/multi-agent-workflow.svg](/examples/multi-agent-workflow.svg)
- **Human page**: [/examples/multi-agent-workflow](/examples/multi-agent-workflow)
- **Manifest**: [/examples/index.json](/examples/index.json)
## Related examples

- [/examples/living-architecture-docs](/examples/living-architecture-docs)
- [/examples/pr-architecture-diff](/examples/pr-architecture-diff)
- [/examples/api-dependency-map](/examples/api-dependency-map)