Workflows are in preview and not yet available in the product.
Example
A reservation manager agent checks the current price of a hotel booking. If the price dropped, it rebooks at the lower rate and a customer support agent emails the guest with the new total. If the price hasn’t dropped, the guest is notified that no action was taken.
POST /v2/workflows
{
"name": "Price drop rebooking",
"description": "Checks hotel price and rebooks if lower",
"runtime_max_ms": 3600000,
"failure_behavior": "stop",
"steps": [
{
"name": "check_price",
"agent_id": "agt_reservations...",
"task_id": "task_check_price..."
},
{
"name": "rebook_if_lower",
"if": "steps.check_price.output.current_price < steps.check_price.output.original_price",
"then": [
{
"name": "rebook",
"agent_id": "agt_reservations...",
"task_id": "task_rebook...",
"input": {
"confirmation_number": "{{ steps.check_price.output.confirmation_number }}"
}
},
{
"name": "notify_savings",
"agent_id": "agt_support...",
"task_id": "task_send_email...",
"input": {
"guest_email": "{{ steps.check_price.output.email }}",
"new_total": "{{ steps.rebook.output.total_cost }}"
}
}
],
"else": [
{
"name": "notify_no_change",
"agent_id": "agt_support...",
"task_id": "task_send_email...",
"input": {
"guest_email": "{{ steps.check_price.output.email }}",
"message": "No price change found"
}
}
]
}
]
}
Running a workflow
Provide a connection for each agent and optional initial input for specific steps. Connections are mapped by agent ID.
POST /v2/workflows/{workflow_id}/run
{
"connections": {
"agt_reservations...": "conn_hilton...",
"agt_support...": "conn_email..."
},
"input": {
"check_price": {
"confirmation_number": "HLT-849271"
}
}
}
{
"id": "wrun_abc123...",
"object": "workflow_run",
"status": "running",
"workflow_id": "wflo_abc123...",
"current_step": "check_price",
"steps": [
{
"name": "check_price",
"task_id": "task_check_price...",
"task_run_id": "trun_xyz...",
"status": "running",
"result": null
},
{
"name": "rebook_if_lower",
"status": "queued",
"branch_taken": null
}
]
}
Step types
A step is either a task step (agent_id + task_id), a sleep step (sleep_ms), or a branch (if / then / else).
Templating
Conditions
Loops
Sleep
Reference output from previous steps using {{ }} syntax in the input field.| Expression | Resolves to |
|---|
{{ steps.check_price.output.email }} | A field from a previous step’s output |
{{ item.id }} | The current item inside a for_each loop |
Use if / then / else to branch based on previous output.{
"name": "decide",
"if": "steps.find.output.cancellable",
"then": [
{ "name": "cancel", "agent_id": "agt_123...", "task_id": "task_def..." }
],
"else": [
{ "name": "notify", "agent_id": "agt_456...", "task_id": "task_xyz..." }
]
}
steps.find.output.cancellable (boolean check)steps.find.output.reservations.length > 0 (array length check)
Use for_each to run a step once per item in an array from a previous step’s output.{
"name": "process_refunds",
"agent_id": "agt_123...",
"task_id": "task_ghi...",
"for_each": "steps.find.output.reservations",
"input": {
"reservation_id": "{{ item.id }}"
}
}
Pause between steps for a specified duration.{
"name": "wait",
"sleep_ms": 30000
}
Interactions
If a step triggers MFA or other verification on the source, the workflow pauses with interaction_required status. The interaction works the same way as connection and task run interactions. Once the user responds, the workflow resumes from where it left off.
Failure behavior
Configure what happens when a step fails. Set failure_behavior at the workflow level.
| Option | Behavior |
|---|
stop | Workflow stops on first failure (default) |
continue | Workflow continues. Failed step is marked, dependents are skipped. |
retry | Retry the failed step before stopping |
Workflow run statuses
| Status | Meaning |
|---|
queued | Waiting to start |
running | Executing a step |
sleeping | Paused between steps |
interaction_required | A step needs user input |
completed | All steps finished |
failed | A step failed and the workflow stopped |
canceled | You canceled the workflow |
Events
| Event | Fired when |
|---|
workflow_run.queued | Workflow is waiting to start |
workflow_run.running | A step is executing |
workflow_run.completed | All steps finished |
workflow_run.failed | A step failed and the workflow stopped |
workflow_run.canceled | You canceled the workflow |
workflow_run.interaction_required | A step needs user input |
