设备接入
协议:WebSocket JSON 控制信令(v1.2,17 条)+ 二进制音频帧 | 鉴权:一机一码 | SDK:C99 与 Python 双实现
接入总览
| 端点 | wss://openagent-os.com/v1/device/ws |
| 鉴权 | 连接即发 auth.hello{device_id, token};token 在控制台「设备」签发(24 字节随机,服务端只存哈希,可吊销) |
| 音频 | 二进制帧:4 字节头 type(0x01 上行/0x02 下行)+flags+seq(大端,双向独立、0xFFFF 回绕);payload ≤2048B;TTS 下行 Opus/24kHz/单声道;丢帧不重传 |
| 会话 | session.start/state/interrupt/error;打断 = session.interrupt → 云端按句边界停止下发 tts.audio 并回 tts.stop{reason:interrupted} |
三步接入
① 控制台签发一机一码
控制台「设备」→ 签发 → 保存 device_id + token(仅显示一次)→
绑定智能体(决定这台设备的提示词/知识库/模型渠道)。
② 选择 SDK
| 平台 | 方案 |
|---|---|
| ESP32-S3 | boards/esp32s3-reference(ESP-IDF 5.x:WS 客户端、I2S 录放、Opus 编解码、按键唤醒/打断、OTA 上报);SDK 以组件形式引用 device-sdk-c/include |
| 树莓派 / Jetson / Linux | Python SDK device-sdk-python(与 C 同契约独立实现,含 Mock 网关与一致性测试) |
| 其他 MCU | 按 protocol/v1/device-protocol.schema.json 自行实现(C 头文件 oa_protocol.h 提供线协议常量与帧封包) |
③ 跑通第一句话
from openagent_sdk import OAClient
client = OAClient(url="wss://openagent-os.com/v1/device/ws",
device_id="dev-…", token="…")
client.on("asr.final", lambda e: print("识别:", e["text"]))
client.on("tts.audio", lambda e: play(opus_decode(e["payload_b64"])))
client.connect()
client.start_session()
client.send_text("你好") # 文本通道快速验证(音频走 send_audio 帧)
离线开发:python -m openagent_sdk.testing 启动 Mock 网关
(schema 校验 + 模拟 VAD/ASR/TTS/打断),无需云端即可开发调试。
运行时行为(云端负责)
- 设备绑定智能体后,云端按智能体配置路由:提示词、知识库检索、LLM 渠道(租户自有渠道优先,否则平台默认渠道)。
- 流式按句下发 TTS(首音预算 <1.2s),打断按句边界生效。
- 对话自动落审计(answer/lead/refusal),命中注入特征拒答并回
biz.handoff转人工。 - 云端可下发
notice.show/config.update/ota.push(控制台「推送」),设备以push.ack回执。
协议契约
完整 Schema:protocol/v1/device-protocol.schema.json(draft 2020-12,
三副本一致性由 tools/audit_scan.py 保障)。版本纪律:v1.x 只允许追加可选字段,
破坏性变更升 v2 双轨。