Run a durable Workflow

Start a durable Workflow when one outcome has a known sequence of two to eight bounded stages and should continue even if the MCP conversation disconnects.

Prerequisites

• Use agents or Full control access.
• An active Agent returned by Crewhelm with the required Skills and Connections.
• One objective and two to eight short, ordered stages.
• Exact Brief revisions needed across all stages.

Authority and custody

Workflow start freezes the owner, Agent and fleet revisions, objective, stage prompts, Briefs, stage timing and deferral windows, aggregate budget, retention, and optional final output contract. The coordinator receives opaque identifiers only. It cannot add work, grant authority, call providers, or bypass normal Run and Tool gate checks.

Every stage executes as a normal bounded Run in one isolated Workflow-owned Session. That Session cannot be continued or deleted as an ordinary Agent conversation.

Start the Workflow

1. Confirm that each stage has one distinct purpose and that later stages depend on earlier output.
2. Call crewhelm_change_work with operation.kind: "start_workflow", the returned Agent object, one objective, and the ordered stages.
3. Add exact Brief revisions without reading and resending their content.
4. Omit outputContract for a Markdown deliverable. If software requires JSON, provide one bounded object-root schema; it applies only to the final stage.
5. Keep the returned Workflow object unchanged.

For a stage that must wait on external processing, add deferral with the maximum elapsed waiting window. Tell the Agent what provider state means done. Its final action must checkpoint either wait, which ends the current Run and resumes the stage later as a fresh bounded Run, or done, which advances the Workflow. Sleeping consumes no Run duration or integration-call budget. Each resumed check consumes its own bounded Run budget within the frozen aggregate Workflow limits. Omitting the checkpoint fails a deferrable stage closed.

Use a direct Run instead when the plan is not yet known. A Workflow is not a general graph or a way to ask the model to invent future authority.

Inspect progress

1. Call crewhelm_inspect_work with operation.kind: "list_workflows" and a small limit.
2. Inspect the selected Workflow with operation.kind: "inspect_workflow".
3. Keep includePrompts false unless debugging the frozen plan.
4. After completion, inspect compact deliverable metadata first. Request deliverable content only when it is needed.

Verify the outcome

• Stages advance in the submitted order.
• A later stage starts only after the prior Run succeeds.
• The final deliverable records exact Workflow, stage, and Run provenance.
• A typed final object is returned as successful only after schema validation.

Recover safely

• Cancel active work through crewhelm_change_work with operation.kind: "cancel_workflow" and the returned Workflow object. Cancellation prevents later stages but cannot undo an already-dispatched external effect.
• Inspect a failed Workflow before starting a replacement. Do not assume a stage made no external change merely because coordination failed.
• Delete only a terminal Workflow with operation.kind: "delete_workflow", the returned Workflow object, owner confirmation, and Full control access. Terminal deletion also removes the Workflow-owned Session, retained execution data, prompts, and deliverable.
• On a revision conflict, inspect the current Workflow and use its returned revision.

Next action

Use Briefs to freeze exact reference material across all stages, or diagnose and recover a failed Workflow.