Skip to main content
Workflows model multi-step processes that can pause for external input and resume when ready. They are designed for approval flows, human-in-the-loop processes, and long-running pipelines with checkpoints.

​
How workflows work

  1. Client sends POST /v1/agents/{name}/workflow to start a workflow
  2. The workflow executes steps sequentially
  3. A step can pause the workflow with a pendingAction requesting external input
  4. Client resumes with POST /v1/workflow-runs/{runId}/resume
  5. The workflow continues from where it paused

​
Starting a workflow

POST /v1/agents/lead-router/workflow
{
  "input": {
    "task": "Route this lead to the right team",
    "state": { "leadId": "lead-123" }
  }
}
​
input.task
string
required
Description of the task for the workflow to execute.
​
input.state
object
Initial state passed into the workflow. Available to all steps.

​
Workflow response

When a workflow pauses, the response includes the current progress, completed steps, and the pending action requiring input. 
{
  "output": {
    "status": "paused",
    "steps": [
      { "name": "classify", "status": "completed", "output": { "category": "enterprise" } }
    ],
    "result": null,
    "pendingAction": {
      "step": "approval",
      "type": "confirmation",
      "message": "Route to enterprise sales team?",
      "options": ["approve", "reject", "escalate"]
    }
  },
  "run_id": "wfr_abc123"
}
​
output.status
string
Current workflow status: running, paused, completed, or failed.
​
output.steps
Step[]
Array of completed and in-progress steps with their names, statuses, and outputs.
​
output.result
object | null
Final result when the workflow completes. null while the workflow is still running or paused.
​
output.pendingAction
object | null
Present when status is paused. Describes what input is needed to continue.
​
run_id
string
Unique identifier for this workflow run. Use it to resume, check status, or cancel.

​
Resuming a workflow

Provide the pending step name and the user’s input to continue execution. 
POST /v1/workflow-runs/wfr_abc123/resume
{
  "input": {
    "resume": {
      "step": "approval",
      "input": "approve"
    }
  }
}
​
input.resume.step
string
required
The name of the paused step to resume.
​
input.resume.input
string | object
required
The external input for the paused step. Must match one of the options if the pending action specifies them.

​
Workflow statuses

StatusDescription
runningWorkflow is actively processing steps
pausedWaiting for external input via pendingAction
completedAll steps finished successfully
failedTerminated with an error

​
Using the SDK

// Start a workflow
const run = await client.agents.workflow("lead-router", {
  input: { task: "Route this lead", state: { leadId: "lead-123" } },
})

if (run.output.status === "paused") {
  // Resume with user decision
  const result = await client.workflowRuns.resume(run.run_id, {
    input: { resume: { step: "approval", input: "approve" } },
  })

  console.log(result.output.status) // "completed"
  console.log(result.output.result)
}

​
Managing workflow runs

EndpointDescription
GET /v1/workflow-runsList all workflow runs for the project
GET /v1/workflow-runs/{runId}Get current status and step details
DELETE /v1/workflow-runs/{runId}Cancel a running or paused workflow
POST /v1/workflow-runs/{runId}/resumeResume a paused workflow with input
// List workflow runs
const runs = await client.workflowRuns.list()

// Get run status
const run = await client.workflowRuns.get("wfr_abc123")
console.log(run.output.status)

// Cancel a run
await client.workflowRuns.delete("wfr_abc123")

​
Best for

  • Approval flows requiring human sign-off
  • Human-in-the-loop processes where AI suggests and humans decide
  • Multi-step pipelines with checkpoints
  • Long-running processes that need external input at specific stages
Workflow runs have a maximum lifetime. If a paused workflow is not resumed within the configured timeout, it will be automatically marked as failed. Check your project settings for the timeout duration.