Workflows

These operations require a connection that exposes flows_ tools. Check your inventory before planning this workflow.

Find and run a workflow

1. Use flows_listWorkflows and flows_getWorkflow to find a definition and inspect its inputs.
2. Gather the required inputs and select the teamspace.
3. Call flows_startWorkflow once.
4. Save the returned execution identifier.
5. Check flows_getWorkflowRunStatus until the execution reaches a terminal state.
6. Retrieve detailed results with flows_getWorkflowRun.

Run our campaign-brief workflow for Acme using this product page. Monitor the existing run and return the final outputs or the failed step.

A workflow definition ID identifies the reusable workflow. A run ID identifies one execution. The start response may label the execution identifier workflow_id; preserve its value as the run ID for run-control tools. The workflow_id in run details refers to the definition.

Understand run states

COMPLETED, FAILED, TERMINATED, and TIMED_OUT are terminal states. RUNNING and PAUSED are not completed results.

If your client disconnects, retrieve the existing run before starting another. Where supported, supply an idempotency_key on start requests to help avoid duplicate submissions.

Control an execution

Restarting can repeat generation and other effects. Inspect the current status and error before choosing retry or restart.

Handle an approval step

When a run is waiting for approval, inspect status with task expansion. Use the returned reference_task_name with flows_approveWorkflowTask and the supported approval outcome. Do not approve an arbitrary task or treat an assistant’s text reply as a recorded workflow approval.

Build or update a workflow

Discover supported actions through flows_listWorkflowActions. Create the definition with flows_createWorkflow, read it back, and use flows_updateWorkflow for revisions. Publish with flows_publishWorkflow when the definition is ready for use. Publishing validates the diagram and creates an executable version; saved edits are not used by new runs until published. If validation fails, fix the reported block before retrying. Keep definition editing, publication, and execution as separate steps so you can verify each result.

Example: build a reusable campaign-brief workflow

Start with a small input/output contract: accept a product description and return a structured campaign brief. Add asset generation or publishing only after that first version works.

1. Discover candidate steps with flows_listWorkflowActions. Inspect each selected action’s input schema and example output.
2. Create a draft with flows_createWorkflow and save the definition ID.
3. Build the diagram and save it through flows_updateWorkflow.
4. Read the definition back with flows_getWorkflow to verify the inputs, connections, and output mapping.
5. Publish with flows_publishWorkflow. Resolve any validation error before starting a run.
6. Start one execution with a small example input, monitor its run ID, and inspect the completed output.
7. Revise and republish the definition before testing a changed version.

Map inputs and outputs correctly

The authoring payload uses extra.diagram; publication builds the executable representation. Each action block needs the action’s discovered reference, its configured inputs, and connections to the next step.

Declare workflow input names in both extra.inputs and the start block’s input schema. Declaring only the names can leave inputs unavailable at execution time. Map outputs using paths that actually exist in the selected action’s example result.

When updating extra, preserve the complete configuration: this field is replaced as a whole. Read the current definition first so a small edit does not remove unrelated settings.

Inspect a failed execution

Use flows_listWorkflowRuns to locate the execution, then read its status and details. Record the failed task, the error, and any outputs already produced. Resolve the cause before retrying; restarting from the beginning can repeat completed side effects.

For human approval, inspect the waiting task and its payload before recording an outcome. The approval tool accepts the documented completion/failure outcomes; a workflow pause and a waiting approval step are different states.

Keep definition changes separate from run control

Editing or republishing a definition does not establish that an existing execution has changed or stopped. Inspect that execution and use the appropriate run-control tool. Delete a workflow definition only when removal is intended, not as a way to cancel one run.

API reference

For request fields, response shapes, and direct HTTP integrations:

• Workflow action discovery
• Publish a definition
• Run status and results

These endpoint pages describe REST requests. For MCP calls, use the current tool schema, including any additional convenience fields.