什么是Realtime Agent
Realtime Agent 是 SenseAudio 平台提供的核心技能模块，专门用于管理与实时代理会话的完整生命周期。该工具通过标准化的 API 接口，帮助开发者实现与语音代理的高效交互，涵盖从会话初始化到资源释放的全流程控制。其设计重点在于确保会话状态的一致性与安全性，尤其强调凭证的持久化存储和短期令牌的安全处理原则。通过清晰的错误分类机制，系统能有效区分配额耗尽、认证失败等可恢复问题，以及参数错误等需修正的问题，从而提升整体服务的健壮性。
核心功能特点
- 支持列出可用代理并选择特定 agent_id
- 提供新建会话或延续现有对话的能力
- 要求将 conv_id 和 room_id 持久化存储于服务端
- 返回短期访问令牌，需按安全规范处理
- 具备完善的错误类型识别与处理机制
- 支持查询房间状态及显式退出会话
适用场景
Realtime Agent 主要面向需要构建实时语音交互系统的场景，例如智能客服、远程协助或自动化语音应答等应用。在这些场景中，开发者首先调用列表接口获取可用的语音代理实例，并根据业务需求选择合适的 agent_id。当用户发起新咨询时，可通过设置 new_dialogue=true 启动全新会话；若需保持上下文连贯（如多轮对话），则使用 new_dialogue=false 并传入已保存的 conv_id 来恢复会话。整个过程中，必须将生成的 conv_id 和 room_id 安全地保存在数据库或服务器端会话中，严禁出现在客户端代码或日志里。对于每次 invoke 操作返回的短期令牌，应视为敏感凭证处理——不得记录、不得嵌入 URL，并在会话结束时立即废弃。当遇到请求失败时，系统能自动判断是临时性的配额不足还是永久性配置错误，指导开发者采取相应措施。最后，在用户结束交互后，务必主动调用 leave 接口释放资源，避免产生不必要的费用或资源占用。