ai-operator/docs/human-handoff.md

Human Handoff / Fallback

TZ-11 adds a safe Human Handoff and fallback layer. The default behavior is intentionally non-transferring.

Purpose

Human handoff gives the AI operator a controlled way to react when the caller asks for a live operator or when automated service cannot safely continue.

Default Behavior

Default configuration:

HANDOFF_MODE=disabled_stub
HANDOFF_ENABLED=false
HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY=true

With these defaults:

• no real transfer is attempted;
• request_human_handoff creates a structured request;
• conversation state moves to HANDOFF;
• the caller receives a safe message that direct transfer is not connected yet.

Handoff Modes

• disabled_stub: records the request and returns a safe message. No ARI transfer.
• ari_redirect: uses ARI channel redirect when explicitly enabled and configured.
• dialplan_continue: returns the channel to dialplan when explicitly enabled and configured.
• hangup_after_message: returns a final message and moves toward closing without transfer.

Real transfer modes require HANDOFF_ENABLED=true and valid target fields. Production routes remain protected.

Config Variables

• HANDOFF_MODE
• HANDOFF_ENABLED
• HANDOFF_TARGET_ENDPOINT
• HANDOFF_DIALPLAN_CONTEXT
• HANDOFF_DIALPLAN_EXTENSION
• HANDOFF_DIALPLAN_PRIORITY
• HANDOFF_QUEUE_NAME
• HANDOFF_TIMEOUT
• HANDOFF_MAX_ATTEMPTS
• HANDOFF_PLAY_MESSAGE_BEFORE_TRANSFER
• HANDOFF_HANGUP_AFTER_STUB
• HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY
• HANDOFF_MAX_SUMMARY_CHARS

Fallback thresholds:

• FALLBACK_MAX_LANGUAGE_FAILURES
• FALLBACK_MAX_REGION_FAILURES
• FALLBACK_MAX_NO_ANSWER
• FALLBACK_MAX_KB_UNAVAILABLE
• FALLBACK_MAX_AI_ERRORS
• FALLBACK_MAX_MEDIA_ERRORS
• FALLBACK_MAX_TOOL_ERRORS
• FALLBACK_CALL_TIMEOUT

Detector Phrases

The handoff detector supports Russian, Kazakh, and mixed/Latin phrases such as:

• оператор
• соедините с оператором
• хочу поговорить с человеком
• операторға қосыңыз
• маман керек
• live agent
• speak to human

Ambiguous business phrases such as оператор связи are not treated as confident handoff requests.

Fallback Scenarios

Fallback manager can offer handoff or safe closing for:

• KB unavailable;
• repeated no-answer;
• repeated language failures;
• repeated region failures;
• AI provider error;
• media error;
• tool error;
• call timeout.

ARI Redirect Mode

ari_redirect calls:

POST /ari/channels/{channelId}/redirect?endpoint={endpoint}

It is only used when enabled and configured. Required tests use fake/httptest clients.

Dialplan Continue Mode

dialplan_continue calls:

POST /ari/channels/{channelId}/continue?context={context}&extension={extension}&priority={priority}

It is only used when enabled and configured.

Production Route

Production routes remain disabled. HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY=true prevents real transfer outside the test route.

Safe Tests

./bin/ai-operator doctor --env /etc/ai-operator/ai-operator.env --check-handoff
./bin/ai-operator handoff-self-test --env /etc/ai-operator/ai-operator.env
./bin/ai-operator fallback-self-test --env /etc/ai-operator/ai-operator.env

These commands do not perform real transfer.

Not Implemented Yet

• real operator queue/extension;
• production handoff enablement;
• call transcript persistence;
• CRM ticket creation;
• operator schedule/availability checks.

Audit Integration

Handoff requests write ai_handoff_audit records with redacted summaries and transfer status. Default disabled_stub does not attempt real transfer.