🤖 给 AI 的参考

这是 Hearo（听见）的《AI 智能体》文档，可作为开发参考。文档链接：https://hearo.apps.aisp24.com/docs/agents.md

AI 智能体

把语音智能体作为参与者调度进房间；提示词 / 模型 / VAD 参数

Hearo 采用「参与者 + 调度」模型（类似 LiveKit Agents / Agora 对话式 AI）：房间是与厂商无关的媒体/数据路由器，AI 智能体是房间的一个参与者。需要 AI 时，控制面把一份「智能体规格」调度给 Go agent-runtime 服务，它便以参与者身份拨入指定房间，跑 ASR→LLM→TTS。

智能体规格（agent spec）

调度时传入，决定这个智能体的一切行为：

字段	类型	说明
instructions	string	系统提示词（人设/任务）
interaction.mode	string	ptt \| multi_turn \| natural
interaction.inactivity_timeout_s	number	多轮模式空闲超时秒数
vad.source	string	server（平台 TEN VAD）\| asr（用 ASR 断句）
vad.threshold	number	0–1，越高越不敏感（抗回声）
vad.min_speech_ms	number	触发打断所需的持续语音时长（抗回声误打断）
vad.min_silence_ms	number	判定一句结束的静音时长
asr / llm / tts	object	各阶段厂商与模型（provider/model/voice…）

💡 VAD 参数是智能体的参数：对话模式与 VAD 灵敏度属于「这个智能体」，在邀请时选择，而非连接房间时。详见交互模式与 VAD。

密钥边界

厂商 API key 从不经过浏览器、也不在调度载荷里。 提示词/模型/模式/VAD 这些非密钥项可由前端传入；而 ASR/LLM/TTS 的密钥由 agent-runtime 从控制台私网拉取（平台在「设置」里配置）。

系统智能体与自有 Provider

在「智能体管理」里，智能体可按环节选用平台默认或你自己的 Provider（填入你自己的 API Key，加密存储）；选了 TTS Provider 后还能为该智能体单独指定音色，覆盖该 Provider 的默认音色。平台管理员还可在运营中心创建系统（公用）智能体，对所有工作空间开放、可直接选用（如「字幕/翻译」智能体）。每个智能体自己选的 Provider / 音色优先生效，平台默认只是回退。

邀请 AI（当前方式）

最简单的方式：在控制台房间的「演示」页连上后点 「邀请 AI 加入」，在面板里选模式、云端 VAD 和灵敏度即可。AI 进房后出现在 roster（kind=agent），可随时移出、或在连接中实时调 VAD。也可给房间配置默认智能体，任何客户端进入即自动邀请（见房间与分组）。

调度接口（内部）

POST <agent-runtime>/v1/agents

由控制面（受信任的后端）调用，鉴权用内部密钥。客户端不直接调用此接口。形态如下：

json

POST /v1/agents
Authorization: Bearer <dispatch secret>
{
  "room": "w_<workspaceId>:demo",
  "workspace_id": "<workspaceId>",
  "agent": {
    "instructions": "你是听见语音助手，回答简洁自然。",
    "interaction": { "mode": "natural", "inactivity_timeout_s": 15 },
    "vad": { "source": "server", "threshold": 0.5, "min_speech_ms": 120 },
    "asr": { "provider": "volcano" },
    "llm": { "provider": "openai-compat" },
    "tts": { "provider": "volcano" }
  }
}
// -> 201 { "agent_id": "ag_...", "room": "...", "identity": "agent-..." }

停止：DELETE /v1/agents/{agent_id}。智能体会离开房间，roster 随之更新。

面向客户的公开 API

除了演示页，你也可以用 API Key 通过 REST 调度智能体（按工作空间鉴权）：

POST /api/v1/agents

bash

curl -X POST https://hearo.apps.aisp24.com/api/v1/agents \
  -H "Authorization: Bearer $HEARO_API_KEY" -H "Content-Type: application/json" \
  -d '{"room":"demo","presetId":"<智能体ID>",
       "overrides":{"vadThreshold":0.6}}'
# -> { "agentId":"ag_...", "room":"demo", "identity":"agent-..." }
# 停止： DELETE /api/v1/agents/{agentId}

presetId 是你在「智能体管理」里保存的智能体（含提示词、Provider、BYO key）；密钥在服务端解析下发，调用方不接触。详见 REST API。