Agent cookbook: canonical sequences

This page is for an MCP-connected agent (or the operator driving one) that already knows the individual tools and wants the proven order to call them in. Every call returns the { success, data } envelope described in the agent reference; sequences 1 and 2 below are the two legal entry surfaces. Each sequence states its preconditions, the numbered calls with their key parameters, what you should see, and where to look when a call refuses.

No sequence in this cookbook lands anything by itself: every path ends at a gate or an accept, and a proposer never approves its own proposal.

Author, publish, invoke

The full authoring loop: from an empty draft to a fresh mission running your graph.

Preconditions — tenant-admin MCP access; a model and provider you are allowed to bind (there is no silent fallback at invoke).

Steps

  1. workflow_catalog — read the palette first: 138 node types in 17 categories, each with its pins. Wire only pin-compatible connections; node types with lifecycle Legacy are publish-blocked in new drafts.
  2. workflow_create_draft — pass your graph payload as graphJson (a minimal skeleton is fine); you get back an id and a workflowId in state Draft, the only editable state. There is no name parameter here — set the display name separately with workflow_rename.
  3. workflow_update_draft — send nodes and wires; repeat as often as needed while the version is still a draft.
  4. Governed graphs only: workflow_materialize injects the required control nodes into your draft — deterministically, before publish — so review them like any node you authored. Use workflow_waive_control with a written reason for a control that can be waived; some controls are non-waivable. See Governance.
  5. workflow_validate_draft — a dry run of the same validator publish uses. It aggregates every problem in one response: fix them all, then validate again — do not fix one and retry.
  6. workflow_publish — freezes the graph into an immutable, checksummed (SHA-256) version. A later rename stays outside the checksum. See what publishing freezes.
  7. workflow_invoke — pass an explicit version (≥ 1: a published version, never a draft), your run parameters (bound at compile time), and model + provider (required unless tenant defaults resolve them) — or bind a named preset with presetId instead, the lever this estate prefers over a raw model (agent reference). Invoke creates a fresh mission around the run.
  8. Watch it: mission_get for mission state, workflow_run_nodes for per-node progress, decision_list for gates waiting on a decision.

Expected outputs — a workflowId; a published version number; a new mission id from the invoke; gates arriving as decisions while it runs.

If it refuses — validation problems (gate dominance, arm reconvergence, a Legacy node, …) all arrive at once under VALIDATION_ERROR; edits to a non-draft return CONFLICT; invoke refuses when the workflow is not invocable. Causes and recoveries: Refusals & failure modes.

Run on an existing mission

The acceptance loop: start a run on a mission that already exists, resolve its gates, then accept or discard what it proposes.

Preconditions — an existing mission that is planned and not terminal; a published workflowId and version; no run already open on the mission — unless you are deliberately competing with a shared groupId.

Steps

  1. mission_run_start — missionId, workflowId, version, parameters; groupId optional. Omit groupId for strict-sequential behavior. Only Started means a run exists — handle all 11 start statuses.
  2. Poll mission_run_get until the run reaches Proposed. While it runs, gates park as decisions: list them with decision_list, resolve them with decision_respond — approve resumes the step, skip cancels it, fail fails it. You never approve a proposal you raised yourself.
  3. Decide. mission_run_accept: on Accepted, exactly one changement lands on the mission branch, and mission_run_get now carries the seal anchors and isAnchored. Acceptance is physical and fail-closed: if no validation backend is reachable in your environment, the accept returns ValidationRefused and nothing merges — the run stays Proposed. On StaleRefused the tip moved underneath you: start a fresh run off the new tip; never retry in a loop. Or mission_run_discard: nothing landed, nothing to undo. All 7 tokens: accept statuses.
  4. mission_changement_stack — the ordered stack of everything accepted so far; the mission's MR is this composed stack. See changements.
  5. To undo an accepted run: mission_revert_preview first — it shows the transitive dependent cascade — then mission_revert, which reverts in reverse ordinal order and fails closed on conflict: the cascade aborts cleanly and names the failing member; nothing partial lands.

Competition variant — start several runs with the same groupId from the same tip (different workflows, parameters, or node instructions). Accept the one you keep; the others are rejected and their branches deleted; a later accept in the group returns GroupAlreadyWon.

Expected outputs — a run id; outcome Proposed → Accepted or Rejected (run outcomes); one changement ordinal per accepted run.

If it refuses — 10 non-Started start tokens and 6 non-Accepted accept tokens, each with a recovery: Refusals & failure modes.

Clone a system template

Preconditions — none beyond MCP access; you clone into your own tenant.

Steps

  1. workflow_system_list — the 22 built-in templates.
  2. workflow_system_get — inspect the graph before you clone; cheaper than cloning just to look.
  3. workflow_clone_from_system — you get a fresh draft you own. Cloning never publishes.
  4. Continue as in sequence 1, steps 3–6: edit, validate, publish.

Templates are representational: cloning gives you the graph to make your own, not a wire into the flow the platform runs internally. See System templates.

Expected outputs — a new workflowId in state Draft, fully editable.

If it refuses — the clone itself rarely refuses; any problems you inherit surface at workflow_validate_draft, all at once — Refusals & failure modes.

Compose by reference

Preconditions — a draft open for editing; the sub-workflow you want to embed has a Published version — only published versions resolve.

Steps

  1. workflow_tile_catalog — the published tiles you can embed, including the sys- building blocks.
  2. Place a FlowRef node via workflow_update_draft. The child's tunnel pins project onto the tile; the child shares your run and your acceptance — composition, never a separate invocation surface.
  3. Before archiving a workflow that others may embed: workflow_referenced_by. Archive is refused while the list is non-empty.
  4. workflow_rebind_flowref — move a consumer to a different target. Rebinding invalidates gate ratification: the affected gates must be re-approved.

Expected outputs — a draft whose FlowRef resolves at validation; workflow_referenced_by returning the live consumers of any published flow.

If it refuses — archiving with live consumers returns CONFLICT; a FlowRef pointing at an unpublished target surfaces at validation. Refusals & failure modes.

Start from a trigger

Preconditions — a published version, and a way off the MCP surface: there is no workflow-trigger MCP tool, so registering the trigger happens in the dashboard or over the platform's REST API. Triggers never fire drafts.

Steps

  1. Publish, as in sequence 1.
  2. Register the trigger outside MCP — either a human uses Manage triggers on the workflow in the dashboard's workflow list, or you call the REST triggers endpoint. Pick one of three kinds: Schedule (a cron expression), Webhook (the endpoint carries a write-only secret — store it at creation, you cannot read it back), or Event (one of the six live seams: mission.created, conversation.completed, support-case.created, incident.created, batch.completed, mr.merged).
  3. Choose the version policy: LatestPublished follows the latest published version; Pinned stays on the one you name. selectedModel and selectedProvider are mandatory on the trigger.
  4. Verify a firing: workflow_runs for the workflow's runs, then mission_get and decision_list on the mission each firing creates.

Every firing behaves like a workflow_invoke: a fresh mission, the same graph, the same gates. Triggers never bypass gates — a triggered run pauses at the same decisions a manual run does.

Expected outputs — one new mission per firing; the runs visible under workflow_runs.

If it refuses — a trigger pointed at an archived or never-published workflow cannot fire; omitting the model or provider refuses at registration. Refusals & failure modes.