Files

Xin Wang b300b469dc Update documentation for Realtime Agent Studio with enhanced content and structure

- Revised site name and description for clarity and detail.
- Updated navigation structure to better reflect the organization of content.
- Improved changelog entries for better readability and consistency.
- Migrated assistant configuration and prompt guidelines to new documentation paths.
- Enhanced core concepts section to clarify the roles and capabilities of assistants and engines.
- Streamlined workflow documentation to provide clearer guidance on configuration and usage.

2026-03-09 05:38:43 +08:00

5.3 KiB

Raw Blame History

助手概念详解

助手（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 由于用户声音活动或者手动请求，是否打断助手当前的回复

能力层

知识库

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

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

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

工具

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

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

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

会话层

`assistant_id` 的作用

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

会话生命周期

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

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

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

动态变量与会话级覆盖

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

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

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

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

5.3 KiB Raw Blame History Unescape Escape