Skip to content

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.

A Human Handoff node on the true branch of a Condition.

Options ​

The Human Handoff panel: Human Type set to Approval, Queue Name billing_approvals, Timeout 1800 seconds, Fallback Action Escalate to parent queue.

FieldWhat it doesOptionsDefaultShown when
Human TypeHandoff (agent takes over) · Approval (agent reviews and resumes)
Queue NameHuman 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 ActionWhat happens on timeoutReturn to AI agent · End conversation · Escalate to parent queue

What happens when the node is reached ​

  1. The run pauses at the node. Nothing downstream runs yet.
  2. 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.
  3. 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 ActionWhat happens on timeoutexit_reason for the next step
Return to AI agentThe run continues to the node after the Human Handoff.human_timeout
End conversationThe run continues to the node after the Human Handoff, flagged as ended. Put your wrap-up steps there.human_timeout_end
Escalate to parent queueThe 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 ​