# 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](/docs/modes)。

## 密钥边界

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

## 系统智能体与自有 Provider

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

## 邀请 AI（当前方式）

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

## 调度接口（内部）

`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](/docs/rest-api)。