1. 概览

当您需要使用自有智能体驱动外呼任务时，CTICloud 将作为语音智能交互底座，负责“听、说、传”，而您的智能体将作为对话大脑，负责“思考与决策”。

核心价值：解耦语音底层技术与业务逻辑，通过 HTTP 接口即可快速集成。
技术栈支持：支持 SSE（Server-Sent Events）协议实现流式响应，保障交互实时性。
灵活配置：支持通道变量传递、多轮对话状态管理、复杂指令（挂机/转人工/按键）下发。

2. 全流程概述

2.1 智能体对接完整流程

┌───────────────────────────────────────────────┐
│            三方智能体对接全流程                 │
└───────────────────────────────────────────────┘

🚀 步骤 1：智能体接口开发
└── 开发者按协议实现鉴权逻辑，确保 API 调用安全。
└── 采用 SSE 协议开发流式响应接口，支持多轮对话与上下文管理。

⚙️ 步骤 2：平台接入配置
├── 在 CTICloud 后台配置智能体调用地址（URL）、appKey 与 secretKey。
└── 在语音导航（IVR）中关联该三方智能体，完成语音底座与大脑的绑定。

📞 步骤 3：实时语音交互
├── 系统自动发起呼叫，ASR 将语音实时转写并发送给三方智能体。
└── 智能体生成回复并下发指令（如#挂机#、#转人工#、按键采集等）。

🔍 步骤 4：联调验证与优化
├── 通过交互日志监控交互请求。

3. 三方智能体接口对接说明

为实现三方智能体与 CTICloud 的对接，整体流程分为两个阶段：

智能体接口开发：您需完成自有智能体的接口开发，确保满足以下要求
- 鉴权认证：遵循《三方智能体接口鉴权认证》文档，对 CTICloud 发起的请求进行鉴权验证
- 请求处理：按照《对接三方智能体接口》文档规范，正确接收和处理 CTICloud 传递的请求参数
  
  您需根据、完成自有智能体的接口开发，确保：
- 响应格式：严格按照接口文档约定的格式返回智能体响应结果
- 接口能力：支持多轮会话、流式响应等高级接口能力
CTICloud 平台接入配置：智能体接口开发完成后，向 CTICloud 提供以下信息用于平台侧接入配置
- 智能体调用地址（URL）
- appKey
- secretKey

CTICloud 平台完成配置后，将在实际语音交互过程中调用客户智能体接口，最终实现端到端的语音对话能力。

{
    "chatHandleParams": {
        "protocol": "https",
        "host": "for.example.com",
        "path": "/path/example",
        "stream": true,
        "appKey": "ThisIsAppKey",
        "secretKey": "ThisIsSecretKey",
        "user": "UserName"
    }
}

3.1 接口请求说明（CTICloud->智能体）

3.1.1 鉴权机制

为保障接口调用过程的安全性，请您在开发智能体接口时，严格按照《三方智能体接口鉴权认证》文档约定的鉴权方式实现相应的鉴权逻辑。在正式调用阶段，CTICloud 将依据该鉴权规则对请求参数进行加密签名，仅当您的服务端按照相同规则完成鉴权校验时，方可确保双方接口的安全、稳定对接。

3.1.2 请求体参数

该部分说明为CTICloud平台对智能体发送请求时携带的参数，您需正确接收对应请求并进行响应。以下为对部分特殊参数的说明：

requestUniqueId：请求唯一标识，每一次请求对应一条 requestUniqueId ，可用于定位双方对接过程中出现的报错问题
conversationId：会话标识，通话开始后，CTICloud 向智能体发起开场白请求后，智能体方返回开场白时，需要同时创建并返回 conversationId 。后续在同一个会话中的信息，都由智能体方通过 conversationId 进行标识。CTICloud 请求内容只包括当前轮次的对话内容，不带全部的历史信息。
userField：userField 为 CTICloud 在调用三方智能体接口时提供的自定义变量字段。接入方可根据实际业务需求，在该字段中传递业务变量，用于支持个性化变量播报、多业务场景路由等场景。
responseMode：支持 streaming 流式模式、 blocking 阻塞模式两种响应模式，一般来说，在外呼机器人场景中，建议使用流式模式来保证交互的实时性。

⭐为保证语音交互效果，首token响应建议低于350ms，最长建议不超过500ms

🗒️平台会自动将各次返回的 token 按顺序拼接成完整文本，您无需自行拼接返回结果。例如：

第一次返回：“你好”，第二次返回：“，张三”，最终播放内容为：“你好，张三”。

若第二次返回：“你好，张三”，平台会继续拼接，最终结果将变为：“你好你好，张三”。

3.2 返回结果说明（智能体->CTICloud）

本节用于说明三方智能体在响应 CTICloud 平台请求时，返回结果所需遵循的格式规范。

3.2.1 流式返回规则说明

在外呼机器人场景中，推荐使用 Streaming（流式）模式进行交互。在流式返回过程中，智能体需按照 SSE（Server-Sent Events）协议，持续向 CTICloud 返回事件数据。具体规则为：

每一条返回内容均应以事件（event）的形式返回；
一次完整的模型回复，通常由多条 message 事件连续组成，用于承载逐步生成的文本内容；
当本次模型回复结束时，需返回 message_end 事件，标识该轮回复完成；
若接口调用过程中发生异常，可返回 error 事件。

3.2.2 事件类型及示例

消息事件（message）

用于承载模型在生成过程中的文本内容片段。

event: message
data:{
  "event": "message",
  "conversationId": "94154941-4c5e-4f40-a898-bef53a9e84a1"
  "answer": {
    "content": "示例1",
    "contentType": "text",
    "createdAt": 1728634543000,
    "messageId": "553fa51b-6e5b-46cb-89ae-c2eb3073b2f6"
  }
}

说明： content 为当前返回的文本片段；一句话或一段完整回复，可能由多条 message 事件按顺序组成。

消息结束事件（message_end）

用于标识本次模型回复已完成。
```
event: message_end
data:{
    "event": "message_end",
    "conversationId": "94154941-4c5e-4f40-a898-bef53a9e84a1",
    "answer": {
        "createdAt": 1728698606000,
        "messageId": "553fa51b-6e5b-46cb-89ae-c2eb3073b2f6"
    }
}
```
说明： message_end 事件用于通知 CTICloud，本轮模型输出已全部完成；收到该事件后，CTICloud 将结束本次流式读取。
异常事件（error）

当接口处理过程中发生异常时，可返回该事件。
```
event: error
data:{
    "event": "error",
    "conversationId": "94154941-4c5e-4f40-a898-bef53a9e84a1"
}
```

4. userField 通道变量使用说明

userField 是 CTICloud 在调用三方智能体接口时提供的自定义变量传递字段。接入方可根据实际业务需求，在该字段中传递业务参数，用于支持个性化播报、业务路由等扩展场景。

4.1 个性化播报：传递用户信息

在外呼业务中，企业通常需要在通话过程中播报与用户相关的个性化信息，例如客户姓名、所在城市或意向产品等。

使用方式：

在任务数据导入或呼叫流程中，通过 userField 传递业务变量至智能体接口：

{
  "userField": {
    "name": "张三",
    "city": "上海",
    "car_model": "TR9"
  }
}

智能体可在对话生成过程中使用上述变量进行个性化话术播报，例如：

"张先生您好，这里是天润客服中心。看到您之前关注过TR9型号，我们这边近期在上海地区有体验活动，诚邀您前来体验。"

4.2 多业务路由：基于参数实现智能体路由

在实际业务中，企业可能同时存在多种外呼业务类型。若为每个业务场景单独配置智能体接口地址，将增加系统维护成本。

推荐方式：采用参数路由，在同一接口 URL 下实现多业务逻辑调度。

🧩实现原理

在接口开发阶段，可在 userField 中预留路由字段，例如：

{
  "userField": {
    "arg": "{arg}"
  }
}

在实际通话过程中，CTICloud 会根据语音导航流程中配置的变量值，将不同的 arg 参数传递至智能体接口。智能体服务端可根据 arg 的取值进行业务路由，从而在同一接口 URL 下调用不同业务逻辑或不同智能体能力。

💡路由配置示例

arg 值	对应业务
car_marketing	汽车营销外呼
after_sale	售后回访
finance	金融咨询

✅ 实现效果

通过该机制可以实现：

一个智能体 URL 接入多个业务场景
基于参数动态路由业务逻辑
无需重复创建智能体配置，降低维护成本

5. 语音交互中接口请求与响应交互示例

5.1 请求示例（CTICloud->智能体）

该部分列举了在真实用户与机器人的交互过程中，在不同的交互场景下，CTICloud对智能体方发起的请求示例。此处仅说明不同场景下当前对话轮次关键信息的请求方式，完整请求示例请参考接口文档。

📞 Scenario1：用户正常在机器人播音结束后说话

"query": [
    {
        "content": "如何重置密码",
        "contentType": "text"
    }
],
"currentChatRound": 10

🗣️ Scenario2：机器人播音过程中，用户说话有效打断机器人播音

playedContent 字段不为空，用于告知大模型，上一轮真正被播音的内容。
"query": [
    {
        "content": "如何重置密码",
        "contentType": "text"
    }
],
"playedContent": "您好，我是上一轮播音被打断时已播放的内容",
"currentChatRound": 10

🔢 Scenario3：用户说话后机器人还未回复用户，用户又说了新的话，触发攒句模式

例如：用户先说话“如何结算”，立即又补充了“使用现金结算”。那么两句话会使用句号“。”进行拼接

cancelRquestUniqueIds 有值，表示触发了攒句。期望模型可以对于历史上下文进行更新，删除该列表对应的请求内容。

触发攒句时模型可能会并发收到多个请求。可通过 currentChatRound 确定请求的先后顺序。

"conversationId": "b1fcdc6123c62be261cf97b00b25be6a2af",
"query": [
    {
        "content": "如何结算。使用现金结算",
        "contentType": "text"
    }
],
"currentChatRound": 10
⏳ Scenario4：机器人播音完成后用户侧持续未说话超过指定时长（时长可自定义）
发送给模型时，使用“(沉默)”用来告知模型客户长时间未说话
"query": [
    {
        "content": "(沉默)",
        "contentType": "text"
    }
],
"currentChatRound": 10

⏳ Scenario4：机器人播音完成后用户侧持续未说话超过指定时长（时长可自定义）

发送给模型时，使用“(沉默)”用来告知模型客户长时间未说话

"query": [
    {
        "content": "(沉默)",
        "contentType": "text"
    }
],
"currentChatRound": 10

5.2 流式响应（智能体->CTICloud）

该部分列举了在实时交互中的不同场景下，智能体向CTICloud返回的响应。

📢 正常进行播音场景

实时响应过程中，智能体方需要流式返回模型的返回内容，CTICloud平台将对其进行拼接，最终完成TTS播报。

当前对话模型返回结束时，需要返回响应结束信息。

# 流式响应
data:{"answer":{"content":"您好","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"很高兴为您服务。","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"请问有什么可以帮您的","contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}

# 响应结束
data:{"answer":{"contentType":"text","createdAt":1752800449},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

🔚需要进行结束性播报并执行挂机操作场景

实时响应过程中，当前通话进行至输出结束语并发起系统挂断时，智能体方的返回内容末尾应该追加#挂机#指令。该指令前后不可添加多余标点符号或其他文本，同时，TTS仅播报返回的对话内容，#挂机#指令不会被播报，该指令仅用于系统识别并进行主动挂断。

当前对话模型返回结束时，需要返回响应结束信息。

# 流式响应，输出挂机操作
data:{"answer":{"content":"感谢您的来电","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"再见。#挂断#","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}

# 响应结束
data:{"answer":{"contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

😄 需要进行转人工播报并执行转人工操作场景

实时响应过程中，当前通话进行至输出转人工话术并发起人工转接时，智能体方的返回内容末尾应该追加#转人工#指令。该指令前后不可添加多余标点符号或其他文本，同时，TTS仅播报返回的对话内容，#转人工#指令不会被播报，该指令仅用于系统识别并发起人工转接。

当前对话模型返回结束时，需要返回响应结束信息。

# 流式响应，输出转人工操作
data:{"answer":{"content":"正在为您转接人工服务","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"请稍等。#转人工#","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}

# 响应结束
data:{"answer":{"contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

🔢需要进行按键采集操作场景

实时响应过程中，若当前通话需要进行按键收集并转移至按键收集状态，智能体方的返回内容末尾应该追加DTMF指令。该指令前后不可添加多余标点符号或其他文本，同时，TTS仅播报返回的对话内容，DTMF指令不会被播报，该指令仅用于系统识别并转移至按键收集状态。

当前对话模型返回结束时，需要返回响应结束信息。

# 流式响应，输出转人工操作
data:{"answer":{"content":"请按键输入您的pin码，按井号键结束。","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"DTMF{6|5|您没有按啊，可以再按一次吗|2|0}","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}

# 响应结束
data:{"answer":{"contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

# 流式响应，输出转人工操作
data:{"answer":{"content":"请按键输入您的pin码，按井号键结束。","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"DTMF_INTERRUPT{6|5|您没有按啊，可以再按一次吗|2|0}","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}

# 响应结束
data:{"answer":{"contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

🔢模型调用工具场景

# 流式响应，输出调用工具事件
data:{"tool":"current_time","conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"agent_thought"}
data:{"answer":{"content":"当前时间是","contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"2025年1月1号1时1分","contentType":"text","createdAt":1752800449},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}

# 响应结束
data:{"answer":{"contentType":"text","createdAt":1752800450},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}