Approval Nodes

Approval nodes pause workflow execution until a human approves or rejects the request. They enable human-in-the-loop automation for scenarios where automated decisions need oversight — large transactions, content publishing, access grants, or any action with significant consequences.

How approvals work

When execution reaches an approval node, the workflow:

  1. Creates an approval record with a snapshot of the current execution context
  2. Saves the current execution state for recovery
  3. Sends notifications to designated approvers
  4. Pauses execution with status Awaiting Approval
Action completes
→
✋ Approval pauses
→
Execution resumes

Configuration

Setting Default Description
Approver mode any Who can approve — any listed user, or require specific users/roles
Approver users — List of user IDs who can approve
Approver roles — List of roles (e.g., admin) whose members can approve
Required approvals 1 Number of approvals needed before execution resumes
Title "Approval Required" Heading shown to approvers
Description template — Jinja2 template rendered with execution context
Context fields — Which context fields to display to approvers
Timeout hours 24 Hours before the approval times out
On timeout fail Action when timeout expires: fail the workflow
Notify via ["email"] Notification channels for approvers

Approval states

A pending approval moves through these states:

✋ Pending Approval
↓
✓ Approved
Execution resumes
↓
✗ Rejected
Workflow fails
↓
⏳ Timed Out
Configurable action
State Description
Pending Waiting for approver action
Approved Required number of approvals received
Rejected An approver rejected the request
Timed Out Timeout period expired without resolution
Cancelled Workflow was manually cancelled or deleted

The approver view

When an approver reviews a pending approval, they see:

Approval Request
Large order requires review
Order #4521 exceeds the $10,000 threshold and needs manager approval before processing.
Customer Acme Corp
Amount $14,250.00
Approvals 0 of 1 required
Approve
Reject

The context fields configured on the approval node determine what data is shown. The description template can pull in any value from the execution context using Jinja2 templates.

Approving and rejecting

Approve — the approver can add an optional comment. Once the required number of approvals is met, the workflow resumes from where it paused.

Reject — the approver must provide a reason. A single rejection immediately fails the workflow regardless of how many approvals have been received.

Each approval and rejection is recorded with the user ID, timestamp, and comment/reason.

Resuming after approval

When enough approvals are collected, the system resumes execution from where it paused. The approval result is stored as the approval node's output and downstream nodes continue executing.

Workflows can resume reliably even after extended approval periods thanks to persistent state storage.

Timeouts

The system periodically checks for timed-out approvals. When a pending approval's timeout period has passed:

  • The approval status changes to Timed Out
  • The configured on_timeout action executes (default: fail the workflow)

Actual timeout resolution may be slightly delayed beyond the configured timeout period due to the periodic check interval.

Multi-approval flows

Set required_approvals greater than 1 to require multiple people to approve. The workflow tracks progress and only resumes when the threshold is met:

  • Each approval increments the count
  • The workflow resumes when the number of approvals meets or exceeds the required threshold
  • Rejection by any single approver immediately fails the workflow

Tool confirmations vs. approval nodes

Approval nodes and tool confirmations both pause a workflow for human review, but they originate differently:

  • Approval nodes are explicit steps you place in the DAG. You decide where in the workflow execution should pause, who can approve, and how many approvals are needed.
  • Tool confirmations are triggered automatically when an agent inside an action node calls a tool that requires confirmation (e.g., sending a message or deleting a record). The workflow pauses the same way, but you didn't place an approval step — the tool's confirmation requirement caused it.

Both appear in the workflow's approval queue. If you want action nodes to run without pausing for tool confirmations, enable Skip tool confirmations in the action node's Advanced Settings.