智能体回调_智能媒体服务(IMS)-阿里云帮助中心

智能体回调允许您的应用在特定事件发生时自动触发预设的操作或响应。通过阅读本文，您可以了解如何使用智能体回调。

功能概述

当智能体在运行过程中触发某些事件时，阿里云将主动向您的服务器发送请求。在接收到回调请求后，您可以添加相应的业务逻辑处理。

配置智能体回调

登录智能融媒体控制台，选择您所需要配置的智能体，单击右侧操作列管理。
单击回调配置页签，开启智能体回调配置，勾选您需要配置回调的类型，并配置回调地址及鉴权Token（可选）。
单击确定，完成智能体回调配置。

回调消息体字段说明

名称	类型	必填	描述	示例值
aiAgentId	String	是	智能体ID。	xxxxx
instanceId	String	是	智能体实例的唯一ID。	39f8e0bc005e4f309379701645f4****
event	String	是	事件类型。智能体状态回调： agent_start：智能体任务已开启。 session_start：通话已建立。 agent_stop：智能体任务已关闭。 error：错误发生。工作流状态回调： intent_detected：开始识别到用户的说话意图时触发。 intent_recognized：识别到较为完整的用户说话意图时触发。 llm_data_received：收到LLM应答数据，对于流式应答，将在第一次收到应答时触发。 tts_data_received：收到TTS应答数据，对于流式应答，将在第一次收到应答时触发。聊天记录实时回调： chat_record：实时聊天记录。用户、智能体音频逐句回调： audio_record：用户音频：当识别到较为完整的用户说话意图时，触发该过程，其内容包括用户的语音数据及其对应的语音识别结果。智能体音频：当智能体结束语音播放或用户主动打断智能体播放时，触发该过程，其内容包括智能体的语音数据以及对应的文本信息。电话呼出状态回调： outbound_call：电话呼出状态以及挂断情况回调。客户端推送的自定义消息回调： client_defined_data：客户端自定义消息发送回调。（建议携带标识，区分消息的开始与结束）	agent_start
data	String	否	实际发送数据，如聊天记录等。	chat_record 消息对话聊天记录： { 'requestId': 'abcd', 'code': 'Success', 'message': 'Success', 'dialogues': [ { 'roundId': 'xxxxxxx', 'producer': 'agent', 'text': '1+1=2', 'reasoningText': '嗯，用户问的是1加1等于多少，这看起来很简单，但我要仔细想一想。', 'time': 1739445458025, 'source': 'chat', 'dialogueId': 'xxxxxxxxxx', 'type': 'normal' }, { 'roundId': 'xxxxxxxxxxx', 'producer': 'user', 'text': '简单回答1+1=？', 'time': 1739445436218, 'source': 'chat', 'dialogueId': 'xxxxxxxxxxx', 'type': 'normal' } ] } 音视频聊天记录： `{ 'role': 'user', 'type': 'normal', 'text': '讲个长点儿的故事', 'sentence_id': 1 }` audio_record `{ 'role': 'user', 'sentence_id': 1, 'start_timestamp': 1743151532.33012, 'text': '讲个长点儿的故事', 'audio_url': '<file oss address>' }` video_frame `{ 'sentence_id': 1, 'start_timestamp': 1743151532.33012, 'text': '我的手里拿着什么？', 'url_list': [<file oss address>, <file oss address>] }`
code	String	是	服务状态码。	1001
message	String	是	具体回调信息。	User has been kicked from the room
timestamp	String	是	时间戳，表示回调事件的发生时间。	2023-10-01T12:00:00Z
userData	String	否	用户自定义信息。
extendData	String	否	定制化扩展信息。

消息体示例：

{
    "aiAgentId":"0d31c************b3c787",
    "instanceId":"39f8e0bc005e4f309379*********",
    "event":"agent_start",
    "code":1001,
    "message":"User has been kicked from the room",
    "timestamp":"2023-10-01T12:00:00Z"
}

事件回调示例

电话呼出状态回调

当event为“outbound_call”，表示回调类型为电话呼出回调；“extendData”内的字段释义如下：

名称	类型	描述
aiAgentId	String	智能体ID。
channelId	String	智能体实例的唯一ID。
instanceId	String	同主消息体字段。
callerNumber	String	主叫（智能体）电话号码。
calleeNumber	String	被叫电话号码。
status	Int	智能体当前通话状态： 2：表示呼出失败； 3：表示呼出成功并接通； 4：表示被叫挂断。
callStartTime	String	电话接通时间。
callEndTime	String	电话挂断时间。
hangupRole	Int	挂断方，0表示主叫，1表示被叫。

电话呼出失败

当使用智能体电话呼出功能时，若被叫方空号、拒接、无法接通时，智能体将发送此回调。回调数据结构如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10002,
  "message":"Dial status failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": -6,
      "status": 2
  }
}

电话呼出成功

使用智能体电话呼出，被叫方接通通话时，智能体将发送此回调。回调数据结构如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10003,
  "message":"Dial status connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3
  }
}

用户挂断

使用智能体电话呼出，被叫方接通后挂断电话，智能体将发送此回调。回调数据结构：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Remote hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 1
  }
}

工作流状态回调

当event为类型为工作流状态回调时，“extendData”内的字段释义如下：

名称	类型	描述
channelId	String	房间ID信息。
sentenceId	Int	问答ID信息。说明对于用户的同一次提问，智能体回答会使用相同的ID信息。
requestTimestamp	String	当event为llm_data_received时，表示向LLM模型发起请求的时间戳信息。当event为tts_data_received时，表示向TTS模型发起请求的时间戳信息。当event为intent_recognized时，表示智能体检测到用户说话结束的时间戳信息。当智能体判断未达到语音结束的检测条件时，此时值为None。
responseTimestamp	String	当event为llm_data_received时，表示从LLM模型收到第一次应答的时间戳信息。当event为tts_data_received时，表示从TTS模型收到第一次应答的时间戳信息。当event为intent_recognized时，表示在用户说话结束后得到ASR识别结果的时间戳信息。

Server 示例

Python

from aiohttp import web
import json
from loguru import logger

async def handle_post(request):
    """
    处理POST请求并记录接收到的数据。
    """
    # 获取请求头中的Authorization
    authorization_header = request.headers.get('Authorization')
    if authorization_header is None or not authorization_header.startswith('Bearer fixed-token'):
        logger.error("Unauthorized request")
        return web.Response(status=401, text='Unauthorized')

    try:
        # 从请求体中获取数据
        callback_data = await request.json()

        logger.info("Parsed JSON data:")
        logger.info(json.dumps(callback_data, indent=4))

        return web.Response(text='Callback received successfully', status=200)
    except json.JSONDecodeError:
        # 如果JSON解析失败，则返回错误响应
        return web.Response(text='Invalid JSON', status=400)

app = web.Application()
app.add_routes([web.post('/', handle_post)])

if __name__ == '__main__':
    web.run_app(app, host='localhost', port=8081)

回调事件状态码

状态码	回调事件	回调信息
1001	智能体启动	AI Agent starts.
1002	智能体终止	AI Agent ends.
1003	会话建立	Session starts
4001	数字人并发路数超额	Concurrent routes exhausted
4002	智能体被踢出房间	User has been kicked from the room
4003	智能体token有误	Invalid token for the AI agent
4004	智能体订阅音频流失败	Failed to pull stream for the AI agent
4005	第三方ASR失败	error description
4006	数字人服务不可用	Avatar service is not available
8001		Intent recognized event
8002		LLM data received event
8003		TTS data received event
10002	电话呼出失败	Dial status failed
10003	电话呼出成功	Dial status connected
10004	用户挂断（电话呼出）	Remote hangup