产品与集成概览

快速阅读

AgentSDK 是给 Web 座席应用用的无界面通话 SDK。页面由业务系统自己画，SDK 负责连接、操作和事件。

• 集成方式：UMD（script 引入，通常挂到 window.AgentSDK）或 ESM（npm 包）。
• 调用模型：操作走 Promise，事件走 on / off / once。
• 登录需要 tenantId、agentNo、sessionKey。软电话还要 HTTPS 和麦克风权限。
• 带界面的工具栏由上层 AgentToolbar 提供。本文说明 Headless 集成。

阅读地图

• 先跑通登录和外呼：读 快速入门。
• 生命周期、uniqueId / mainUniqueId、重连：读 核心概念与生命周期。
• 方法参数：读 API（操作）。
• 事件载荷：读 事件。
• 状态取值：读 状态机：状态/状态转移。
• 类型定义：读 类型。排障：读 错误处理。

一、文档说明

本文说明 AgentSDK 在座席工作台集成里的位置：它提供电话能力和事件通知，不提供座席工作台界面。

适用：把座席接听、外呼、转接嵌进自有 Web 系统的前端开发人员。

二、SDK 提供什么

• 连接管理、事件模型、心跳检测与断线重连。
• UMD 与 ESM 两种集成方式。
• 统一约定：Operations（Promise）+ Events（on / off / once）。

带界面的工具栏使用基于 AgentSDK 封装的 AgentToolbar。

三、集成方式

3.1 UMD

通过 <script> 引入构建产物。SDK 挂载到 window，全局名称通常为 window.AgentSDK。

3.2 ESM

通过 npm / pnpm / yarn 安装，在业务代码里按模块引入。

四、接入前确认

• HTTPS：麦克风权限通常要求 HTTPS，尤其是 WebRTC 软电话。
• 浏览器权限：授予麦克风访问权限，并确认企业策略或浏览器策略未拦截。
• 网络：baseURL（Agent Gateway 接入地址）可访问。
• 身份凭证：登录时提供有效的 tenantId、agentNo、sessionKey。

五、数据流

AgentSDK 主要通过 WebSocket 与后端通信。

• 发起操作：sdk.method(params) → 后端处理 → 返回操作响应（Promise resolve）。
• 接收通知：sdk.on(EventType.X, handler) 接收事件。

先用 Promise 结果判断该操作成功或失败，再用事件驱动界面和业务流程（座席状态、通话里程碑）。

六、和其他文档的分工