Implement automatic hang-up or transfer-Intelligent Media Services(IMS)-阿里云帮助中心

Feature introduction

Automatic hang-up and transfer enables an AI agent to proactively end or transfer a call after detecting the user's intent to do so, or upon completing its assigned task.

Use cases

User-initiated hang-up: During a conversation, if the user says something like, "I have to go," or "No thanks, that's all," the agent recognizes this intent and immediately hangs up the call.
Agent-initiated hang-up after task completion: When the agent has completed its objective, such as confirming information or creating an order, it can play a closing remark and automatically hang up for a natural conclusion to the call.
Rule-driven smart transfer: If a user's request is beyond the agent's capabilities, the agent can hand off the call to a human agent based on pre-defined rules.

Comparison of implementation methods

Choose one of the following methods based on your business needs and technical architecture.

Method	Description	Recommended scenarios	Supported features
Using text commands output by the LLM	Define a special text command in the large language model (LLM)'s prompt to guide the LLM to output this command when a hang-up is needed.	Simple, model-agnostic implementations that don't require complex API configuration and allow for precise control over actions via prompts.	Automatic hang-up, automatic transfer
Using the LLM's `tool_calls`	Follow the OpenAI Function Calling specification to encapsulate the hang-up function as a tool for the LLM to call.	For integrations with custom LLMs that follow the OpenAI protocol, enabling structured and more reliable function calls.	Automatic hang-up

Method 1: Using text commands output by the LLM

This method only requires you to guide the LLM to output a specific text command when a hang-up or transfer is needed.

Hang-up command

Command format

<imsagent_hangup endword="closing_message"/>

Parameter:

endword: The closing remarks to play to the user before hanging up. The call will be automatically disconnected after the message is played.

Example

<imsagent_hangup endword="I'll hang up now, goodbye!"/>

Transfer command

Command format

<imsagent_transfer_call caller="caller_number", callee="callee_number", err_msg="transfer_failed_message", msg="transfer_success_message"/>

Parameters:

caller: The caller's number (the current user's number or a virtual number set by the service).
callee: The callee's number (the transfer destination).
err_msg: The message to play to the user if the transfer fails.
msg: The message to play to the user when the transfer is initiated.

Example

<imsagent_transfer_call caller="111111", callee="123", err_msg="Sorry, the line is busy.", msg="Transferring your call now..."/>

Sample prompt

Add the following instructions to your prompt to guide the LLM to use hang-up and transfer commands at the appropriate time.

You are an intelligent voice assistant with the following capabilities:
1. When you need to hang up the call, output in the following format:
<imsagent_hangup endword="closing_remarks"/>
Example:
<imsagent_hangup endword="I'll hang up now, goodbye!"/>
2. When you need to transfer the user to a number, output in the following format:
<imsagent_transfer_call caller="caller_number", callee="callee_number", err_msg="transfer_failed_message", msg="transfer_message"/>
Example:
<imsagent_transfer_call caller=111111, callee=123456, err_msg="Sorry, the line is busy.", msg="Transferring your call now..."/>

Method 2: Using the LLM's tool_calls

Agent startup API configuration

To enable automatic hang-up, map the system's built-in hang-up function to an LLM function via LlmConfig.FunctionMap when starting the agent instance.

Audio/Video calls: When you call StartAIAgentInstance, configure LlmConfig in AIAgentConfig.

Phone calls: When you call StartAIAgentOutboundCall, configure LlmConfig in AIAgentOutboundCallConfig.

LlmConfig:

Field	Type	Description	Example
FunctionMap	array<object>	A list of function mappings that associates agent capabilities with LLM functions. Currently, only function calls for custom LLMs that use the OpenAI protocol are supported.	`[{ "Function": "hangup", "MatchFunction": "hangup" }]`
-Function	string	The name of the built-in function provided by the agent system. Currently, only `hangup` is supported.	hangup
-MatchFunction	string	The name of the corresponding LLM function. This is user-defined and used to call the function in the LLM. For more information, see LLM standard interface.	hangup

FunctionMap maps functions defined in the LLM to the built-in capabilities of the agent system. When the system detects the function name defined in MatchFunction in the LLM's tool_calls response, it executes the built-in function specified by Function. This mapping is required. If no name conversion is needed, you can set both Function and MatchFunction to hangup.

Implement the LLM's tool_calls

Use the LLM's native capabilities or other algorithms to determine whether to hang up, then return the tool_calls in the OpenAI protocol format. For details, see LLM standard interface.

def generate_stream_response(data):
    response = "This is a simulated streaming response from the AI assistant."
    words = list(response)
    for i, word in enumerate(words):
        chunk = {
            "id": "chatcmpl-123",
            "object": "chat.completion.chunk",
            "created": int(time.time()),
            "model": data['model'],
            "choices": [{
                "index": 0,
                "delta": {
                    "content": word, 
                    "tool_calls": [  
                        {
                            "id": "call_abc123",  
                            "type": "function",
                            "function": {
                                "name": "hangup", 
                                "arguments": "\{\}"  
                            }
                        }
                    ]
                },
                "finish_reason": None if i < len(words) - 1 else "stop"
            }]
        }
        logger.info(chunk)
        yield f"data: {json.dumps(chunk)}\n\n"
        time.sleep(0.1)  # Simulate processing time 

    yield "data: [DONE]\n\n"