Human Handoff
Some steps shouldn't run without a person: a refund over a limit, a policy exception, a case your team wants to see first. The Human Handoff node is a pause point for that. When a run reaches it, the run stops, your team is notified, and nothing after the node happens until the pause ends.
You'll find it under Core in the node picker. You can also add it as a step inside an agent's Steps.

Options

| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Human Type | Handoff (agent takes over) · Approval (agent reviews and resumes) | |||
| Queue Name | Human queue this hands off to. Use the same name configured in your Queue management. Convention: snake_case, e.g. senior_underwriter, tier_1_support, vip_escalation. | |||
| Timeout (seconds) | How long to wait for a human to claim before the fallback fires. Common values: 300 (5 min — quick chat), 3600 (1 hr — email-class response), 86400 (24 hr — overnight ops). Schema enforces min 60 / max 604800 (7 days). | |||
| Fallback Action | What happens on timeout | Return to AI agent · End conversation · Escalate to parent queue |
What happens when the node is reached
- The run pauses at the node. Nothing downstream runs yet.
- A notification appears in the Studio notification bell: Workflow handed off to a human, with the queue name. If the run belongs to a conversation, the notification links to it in Conversations.
- The run stays paused until the task is resolved or the timeout passes. Once a minute, Perfox checks for tasks that have passed their timeout and applies the Fallback Action:
| Fallback Action | What happens on timeout | exit_reason for the next step |
|---|---|---|
| Return to AI agent | The run continues to the node after the Human Handoff. | human_timeout |
| End conversation | The run continues to the node after the Human Handoff, flagged as ended. Put your wrap-up steps there. | human_timeout_end |
| Escalate to parent queue | The run stays paused and a louder notification goes out: Human task timed out, needs attention. | (still paused) |
Pick the fallback that matches the stakes. A low-risk review can safely Return to AI agent. A step that must never proceed on its own should Escalate to parent queue.
Branch on the outcome
Add a Condition (IF/ELSE) after the Human Handoff and branch on exit_reason. For example, with Switch on exit_reason and the cases human_timeout and human_timeout_end, each fallback gets its own path.
Worked example: an approval gate at Acme Support
Setup. Asha builds Acme Support's refund workflow. After the agent collects the order details, she adds a Human Handoff with Human Type set to Approval, Queue Name billing_approvals, Timeout 1800 seconds, and Fallback Action set to Escalate to parent queue. A Condition after it switches on exit_reason.
Action. Priya asks for a refund on a large order. The agent gathers the order number and reaches the Human Handoff. The run pauses and a billing_approvals notification appears in Asha's team's notification bell.
Result. If nobody acts within 30 minutes, the run stays paused and a second, louder notification goes out, so the refund is never processed without a person seeing it.
What just happened. The agent handled the routine part of the conversation. The one step Acme's policy says needs a person could not run until the pause ended.
Need a person to take over a live chat or call?
The Human Handoff node pauses a workflow run. To hand a live conversation to one of your people, or transfer a live phone call to a number, add the Hand off to Human action to your AI Agent instead. See AI Agent Node.
Next steps
- Condition (IF/ELSE): branch on how the pause ended.
- Steps (Agent Process): add a Human Handoff inside an agent's step-by-step process.
- Conversations: where the notification's link takes your team.