# 助手概念详解

助手（Assistant）是 Realtime Agent Studio（RAS）中最核心的配置单元，也是控制台和 API 对外暴露能力的基本对象。

---

## 什么是助手

一个助手代表一个可接入、可测试、可发布的实时 AI 入口。它回答三个问题：

- **它是谁**：角色、语气、目标、限制、开场方式、静默时候的行动（比如静默时候的询问 Ask-on-Idle）
- **它能做什么**：语言模型能力、语音模型能力（ASR、TTS、用户打断灵敏度（Barge-in）、语句端点设置（End-of-Utterance））、知识库、记忆、工具（Webhook、客户端工具、系统工具、MCP）、输出模式
- **它在一次会话中如何运行**：通过 `assistant_id` 载入配置，并在运行时接收动态变量、对话时候的上下文更新

如果把引擎理解为“运行时”，那么助手就是“运行时要执行的那份定义”。

## 助手由哪些部分组成

| 层次 | 负责什么 | 典型内容 |
|------|----------|----------|
| **身份层** | 定义助手角色和交互风格 | 系统提示词、限制、开场白、静默处理 |
| **模型层** | 决定理解与生成能力 | LLM、ASR、TTS、引擎类型、用户打断、语句端点 |
| **能力层** | 扩展知识和执行能力 | 知识库、工具、记忆 |
| **会话层** | 决定运行时上下文如何注入 | `assistant_id`、动态变量 |

## 身份层

助手首先是一个“被约束的角色”，而不是一段孤立的模型调用。

### 系统提示词

系统提示词定义助手的角色、任务、边界和风格，是所有能力组合的基础。

| 要素 | 作用 | 示例 |
|------|------|------|
| **角色** | 告诉模型“自己是谁” | 客服助手、销售顾问、培训教练 |
| **任务** | 指定要完成的结果 | 解答咨询、收集信息、调用工具处理业务 |
| **限制** | 明确哪些事不能做 | 不承诺超权限优惠、不输出未经验证的结论 |
| **风格** | 约束回答节奏和措辞 | 简洁、口语化、每次 2-3 句 |

### 开场白

一个助手还要定义会话应该如何开始，以及用户静默时候如何处理，包括：

- **首轮模式**：助手先说、用户先说或者机器先说
- **开场白**：使用固定开场白或者AI生成开场白

### 静默处理

用户静默时候是否询问用户是否在线

## 模型层

模型决定助手的基础理解、推理和表达能力，但不是助手定义的全部。

- **LLM** 决定对话推理与文本生成能力
- **ASR** 决定语音输入如何被实时转写
- **TTS** 决定文本回复如何转成可播放语音
- **引擎类型** 决定运行链路是分段可控还是端到端低延迟
- **VAD** 声音活动模型，判断用户是否在说话
- **EOU** 语句端点模型，判断用户是否完成一段语句等待回复
- **Barge In** 由于用户声音活动或者手动请求，是否打断助手当前的回复

## 能力层

### 知识库

知识库用于补充私有领域知识，让助手回答超出基础模型常识之外的问题。

```mermaid
flowchart LR
    Question[用户问题] --> Retrieval[检索]
    Retrieval --> KB[(知识库)]
    KB --> Context[相关片段]
    Context --> LLM[LLM]
    LLM --> Answer[回答]
```

知识库适合承载政策、产品资料、流程说明、FAQ 和内部文档，而不是把所有业务知识堆进系统提示词。

### 工具

工具让助手从“会说”变成“能做事”。

```mermaid
flowchart LR
    User[用户] --> Assistant[助手]
    Assistant --> Tool[工具 / 外部系统]
    Tool --> Assistant
    Assistant --> User
```

适合用工具处理的任务包括：订单查询、预约、外部搜索、写入业务系统、调用客户端能力等。

## 会话层

### `assistant_id` 的作用

在接入层面，客户端通过 `assistant_id` 指定要加载哪一个助手。引擎据此读取默认配置，并把同一份助手定义应用到当前会话。

### 会话生命周期

```mermaid
stateDiagram-v2
    [*] --> Connecting: WebSocket 连接
    Connecting --> Started: session.started
    Started --> Active: config.resolved / 开始对话
    Active --> Active: 多轮交互
    Active --> Stopped: session.stop 或连接关闭
    Stopped --> [*]
```

一次会话通常会沉淀以下信息：

- 用户与助手消息时间线
- 音频流、转写结果和模型输出
- 工具调用记录与中间事件
- 自定义 metadata、渠道和业务上下文


### 动态变量与会话级覆盖

助手的默认配置不需要为每个用户都重新复制一份。RAS 提供两种常见的运行时注入方式：

- **动态变量**：在提示词中使用 `{{variable}}` 占位，并在会话开始时传入具体值
- **会话级覆盖**：仅对当前会话覆盖部分运行时参数，不回写助手基线配置

```json
{
  "type": "session.start",
  "metadata": {
    "dynamicVariables": {
      "company_name": "ABC 公司",
      "customer_name": "张三",
      "tier": "VIP"
    }
  }
}
```

这种设计让你既能复用标准助手，又能在每次接入时注入渠道、用户、订单或上下文信息。

## 相关文档

- [配置选项](assistants/configuration.md) - 查看助手在控制台和运行时有哪些配置层
- [提示词指南](assistants/prompts.md) - 设计角色、任务、限制和语气
- [测试调试](assistants/testing.md) - 验证助手质量并定位问题