Tool-Managed Handover functionality and limitations

Overview

This documentation explains the design limitations and proper configuration of Tool-Managed Handover functionality. Understanding these constraints will help you configure your handover tools correctly and avoid unexpected behaviors.

Key Design Principle

Tool-Managed Handover vs. Fallback Prompts: The system uses either a fallback tool or a fallback prompt, never both. When Tool-Managed Handover is enabled, the configured fallback prompt is bypassed in favor of the tool-based approach.

System Design & Limitations

How Tool-Managed Handover Works

1. Root Agent Execution: Before breaking out, the root agent executes the configured handover tool

2. Tool Success: If the tool executes successfully, the handover proceeds as defined by the tool

3. Tool Failure: If the tool fails for any reason, the system returns a static fallback message that is not configurable or translated into the customer's language.

Current Limitations and Workarounds

1. Parameter Restrictions: The handover tool cannot have parameters other than those defined in the Template Handover tool, language, and userInput

2. Workaround for Additional Parameters: If you need other parameters, use User Interactions to collect them before proceeding with the desired functionality.

Agent Configuration Constraints

Handover Only Root Agent with Handover Tool - Edge Case

Problem: When a root agent is configured as "Handover Only" and also has the Handover Tool as one of its options, a recursive loop can occur.

Scenario:

• The user immediately requests, "I want to speak to a live agent."

• Root agent correctly calls the Handover Tool

• The tool executes successfully and returns the result to the Root Agent

• Since Root Agent is "Handover Only", it cannot relay the tool result to the user

• Root Agent must perform another handover/tool call

• Root Agent chooses Handover Tool again, asking for the first name repeatedly

Root Cause: Handover Only agents can only perform tool calls or handovers to other agents - they cannot communicate tool results directly back to users.

Solution: Create a dedicated handover agent:

1. Create New Agent: Design an agent that is not "Handover Only"

2. Single Purpose: Configure it only to handle calling the Handover Tool or breaking out if the user doesn't want handover

3. Update Root Agent: Instead of referencing the Handover Tool directly, reference this new Handover Agent

Important Notes

• When Tool-Managed Handover is active, your custom fallback prompts will not be used

• Always test your handover tool configuration to ensure it handles edge cases appropriately and does not fail

• Consider the static fallback message behavior when designing your handover flow

• Avoid configuring Handover Only agents with direct access to Handover Tools - use dedicated handover agents instead