产品与集成概览

1. 什么是 AgentSDK？

AgentSDK 是一个面向 Web 座席应用的企业级**无界面（UI-less / Headless）**通话 SDK，提供适用于联络中心场景的电话能力与事件通知机制：

• 内置连接管理、事件模型、心跳检测与断线重连能力
• 同时支持 **UMD（script 标签引入）和 ESM（npm 包）**两种集成方式
• 以 Operations（Promise）+ Events（on/off/once） 的形式对外提供统一能力约定

如果你只需要一个带界面的工具栏（插件版），通常会由基于 AgentSDK 封装的上层 AgentToolbar 提供。本文档聚焦于 API/SDK（Headless，无界面）集成。

2. 集成方式

2.1 UMD（适用于页面直接引入）

• 通过 <script> 引入构建产物
• SDK 会挂载到 window 上（全局名称通常为 window.AgentSDK）

2.2 ESM（适用于现代构建系统）

• 通过 npm / pnpm / yarn 安装
• 在业务代码中按模块方式引入 SDK

3. 前置条件（必须确认）

• HTTPS：麦克风权限通常要求在 HTTPS 环境下使用，尤其是 WebRTC 软电话场景
• 浏览器权限：必须授予麦克风访问权限，同时确认企业策略或浏览器策略未拦截
• 网络连通性：需要确保 baseURL（Agent Gateway 接入地址）可正常访问
• 身份凭证：登录时需要有效的 tenantId / agentNo / sessionKey

4. 高层数据流

AgentSDK 主要通过 WebSocket 与后端服务通信：

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

典型使用方式：

• 优先判断 Promise 结果：用于确认该操作最终是成功还是失败（推荐）
• 再处理事件通知：用于驱动 UI 更新和业务流程编排（如状态变化、通话里程碑等）

5. 阅读指引

• 首次集成：建议先阅读 Quick-Start，再阅读 Core-Concepts-and-Lifecycle
• 故障排查：建议先查看 Error-Handling，再结合 Events 与 State-Machine-stateAction
• 类型或 TS 开发：请以 Types 作为最终准确依据