配置响应超时承接语

当智能体需要较长时间检索资料、调用工具或生成回复时，你可以配置承接词，让 AI 在等待期间先播报一句简短提示，减少等待过程中的静默。承接词支持使用预定义文本，也支持根据最后一条用户消息动态生成。

前提条件

开始前，请确保你已参考使用 RESTful API 实现对话式 AI 引擎或使用 Agents SDK 实现对话式 AI 引擎实现基本对话。

选择承接词模式

通过 filler_words.content.mode 选择承接词来源：

• static：（默认）从 static_config.phrases 中选择预定义承接词。省略 mode 时保持该行为。
• generated：根据当前对话动态生成承接词。你可以按需配置 generated_config 覆盖服务端默认生成设置，也可以配置 static_config 作为静态回退。

信息

generated 模式必须显式设置。动态承接词生成服务由声网托管，RESTful API 和 Agents SDK 均不需要、也不支持配置生成模型的地址、密钥或参数。generated_config 和 static_config 均为可选配置；省略 generated_config 时，服务端使用默认生成设置。

了解触发时序

对于符合条件的语音输入或 POST 发送自定义指令，引擎会同时启动主 LLM 请求和动态承接词生成：

1. 如果主 LLM 在 response_wait_ms 到期前产生可播报内容，直接播报主回复，不播报承接词。
2. 如果到期时主 LLM 仍在等待，且动态承接词已经就绪，播报动态承接词。
3. 如果动态承接词未就绪、生成失败或内容无效，且配置了 static_config，播报一条静态回退承接词。
4. 播报承接词不会取消、丢弃或重新启动主 LLM 请求。主回复就绪后继续播报。

每个回合最多播报一条承接词。迟到的动态承接词不会替换已经选择的内容，也不会触发第二次播报。预取回合不会触发承接词。

配置静态承接词

Go

Go

// --- 此处省略智能体的其他配置 ---

agent := agentkit.NewAgent(
	client,
	agentkit.WithFillerWords(&agentkit.FillerWordsConfig{
		Enable: Agora.Bool(true),
		Trigger: &agentkit.FillerWordsTrigger{
			Mode: Agora.String("fixed_time"),
			FixedTimeConfig: &agentkit.FillerWordsTriggerFixedTimeConfig{
				ResponseWaitMs: Agora.Int(1500),
			},
		},
		Content: &agentkit.FillerWordsContent{
			Mode: agentkit.FillerWordsContentModeStatic.Ptr(),
			StaticConfig: &agentkit.FillerWordsContentStaticConfig{
				Phrases:       []string{"请稍等。", "我正在为你查询。", "好的。"},
				SelectionRule: agentkit.FillerWordsSelectionRuleShuffle.Ptr(),
			},
		},
	}),
)

Python

Python

# --- 此处省略智能体的其他配置 ---

from agora_agent import (
    Agent,
    FillerWordsConfig,
    FillerWordsContent,
    FillerWordsContentStaticConfig,
)

agent = Agent(client=client).with_filler_words(
    FillerWordsConfig(
        enable=True,
        content=FillerWordsContent(
            mode="static",
            static_config=FillerWordsContentStaticConfig(
                phrases=["请稍等。", "我正在为你查询。", "好的。"],
                selection_rule="shuffle",
            ),
        ),
    )
)

Python 示例使用默认的 fixed_time 触发模式和 1500 ms 等待阈值。

TypeScript

TypeScript

// --- 此处省略智能体的其他配置 ---

const agentWithFillerWords = agent.withFillerWords({
  enable: true,
  trigger: {
    mode: 'fixed_time',
    fixed_time_config: { response_wait_ms: 1500 },
  },
  content: {
    mode: 'static',
    static_config: {
      phrases: ['请稍等。', '我正在为你查询。', '好的。'],
      selection_rule: 'shuffle',
    },
  },
});

RESTful API

以下配置会在主 LLM 等待时间达到 1500 ms 时，从预定义列表中选择一条承接词：

JSON

{
  "filler_words": {
    "enable": true,
    "trigger": {
      "mode": "fixed_time",
      "fixed_time_config": {
        "response_wait_ms": 1500
      }
    },
    "content": {
      "mode": "static",
      "static_config": {
        "phrases": [
          "请稍等。",
          "我正在为你查询。",
          "好的。"
        ],
        "selection_rule": "shuffle"
      }
    }
  }
}

参数说明

Go

参数	类型	必选	说明
FillerWordsConfig.Enable	*bool	否	是否启用承接词。使用静态模式时必须配置 Content.StaticConfig。默认值：false。
FillerWordsTrigger.Mode	*string	否	承接词触发模式。默认值：fixed_time。
FillerWordsTriggerFixedTimeConfig.ResponseWaitMs	*int	否	LLM 响应等待阈值，单位为毫秒。取值范围为 100 到 10000。默认值：1500。
FillerWordsContent.Mode	*FillerWordsContentMode	否	承接词内容模式。静态模式使用 FillerWordsContentModeStatic。
FillerWordsContentStaticConfig.Phrases	[]string	是	静态承接词列表，支持 1 到 100 个非空字符串。
FillerWordsContentStaticConfig.SelectionRule	*FillerWordsContentSelectionRule	否	承接词选择规则。支持 shuffle 和 round_robin。默认值：shuffle。

Python

参数	类型	必选	说明
enable	bool	否	是否启用承接词。使用静态模式时必须配置 content.static_config。默认值：False。
content.mode	str	否	承接词内容模式。静态模式设置为 static，也可以省略。
content.static_config.phrases	List[str]	是	静态承接词列表，支持 1 到 100 个非空字符串。
content.static_config.selection_rule	str	否	承接词选择规则。支持 shuffle 和 round_robin。默认值：shuffle。
触发配置	—	否	未显式设置时使用 fixed_time 模式，等待阈值为 1500 ms。

TypeScript

参数	类型	必选	说明
enable	boolean	否	是否启用承接词。使用静态模式时必须配置 content.static_config。默认值：false。
trigger.mode	string	否	承接词触发模式。默认值：fixed_time。
trigger.fixed_time_config.response_wait_ms	number	否	LLM 响应等待阈值，单位为毫秒。取值范围为 100 到 10000。默认值：1500。
content.mode	string	否	承接词内容模式。静态模式设置为 static，也可以省略。
content.static_config.phrases	string[]	是	静态承接词列表，支持 1 到 100 个非空字符串。
content.static_config.selection_rule	string	否	承接词选择规则。支持 shuffle 和 round_robin。默认值：shuffle。

RESTful API

参数	类型	必选	说明
enable	Boolean	否	是否启用承接词。使用静态模式时必须配置 content.static_config。默认值：false。
trigger.mode	String	否	承接词触发模式。默认值：fixed_time。
trigger.fixed_time_config.response_wait_ms	Integer	否	LLM 响应等待阈值，单位为毫秒。取值范围为 100 到 10000。默认值：1500。
content.mode	String	否	承接词内容模式。设置为 static 或省略时，使用静态承接词。默认值：static。
content.static_config	Object	是	静态承接词配置。启用承接词时必须配置。
content.static_config.phrases	Array of String	是	静态承接词列表，支持 1 到 100 个非空字符串。
content.static_config.selection_rule	String	否	承接词选择规则。支持 shuffle 和 round_robin。默认值：shuffle。

配置动态承接词

Go

Go

// --- 此处省略智能体的其他配置 ---

agent := agentkit.NewAgent(
	client,
	agentkit.WithFillerWords(&agentkit.FillerWordsConfig{
		Enable: Agora.Bool(true),
		Content: &agentkit.FillerWordsContent{
			Mode: agentkit.FillerWordsContentModeGenerated.Ptr(),
			StaticConfig: &agentkit.FillerWordsContentStaticConfig{
				Phrases: []string{"请稍等。", "我正在处理。"},
			},
			GeneratedConfig: &agentkit.FillerWordsContentGeneratedConfig{
				Prompt: "根据当前对话生成一句简短、自然的承接词，不要直接回答用户问题。",
			},
		},
	}),
)

Go 示例未显式设置 Trigger 和 FallbackStrategy，分别使用默认的 fixed_time/1500 ms 和 static。

Python

Python

# --- 此处省略智能体的其他配置 ---


generated = FillerWordsConfig(
    enable=True,
    content=FillerWordsContent(
        mode="generated",
        static_config=FillerWordsContentStaticConfig(
            phrases=["请稍等。", "我正在处理。"],
        ),
        generated_config=FillerWordsContentGeneratedConfig(
            prompt="根据当前对话生成一句简短、自然的承接词，不要直接回答用户问题。",
        ),
    ),
)
agent = Agent(client=client).with_filler_words(generated)

Python 示例未显式设置触发配置和回退策略，使用默认的 fixed_time/1500 ms 和 static。

TypeScript

TypeScript

// --- 此处省略智能体的其他配置 ---

const agentWithGeneratedFillerWords = agent.withFillerWords({
  enable: true,
  trigger: {
    mode: 'fixed_time',
    fixed_time_config: { response_wait_ms: 1500 },
  },
  content: {
    mode: 'generated',
    static_config: {
      phrases: ['请稍等。', '我正在处理。'],
      selection_rule: 'shuffle',
    },
    generated_config: {
      prompt: '根据当前对话生成一句简短、自然的承接词，不要直接回答用户问题。',
      fallback_strategy: 'static',
    },
  },
});

RESTful API

将 content.mode 设为 generated，并保留静态回退内容：

JSON

{
  "filler_words": {
    "enable": true,
    "trigger": {
      "mode": "fixed_time",
      "fixed_time_config": {
        "response_wait_ms": 1500
      }
    },
    "content": {
      "mode": "generated",
      "static_config": {
        "phrases": [
          "请稍等。",
          "我正在处理。"
        ],
        "selection_rule": "shuffle"
      },
      "generated_config": {
        "prompt": "根据当前对话生成一句简短、自然的承接词。不要直接回答问题或声称任务已经完成，只返回承接词文本。",
        "fallback_strategy": "static"
      }
    }
  }
}

参数说明

Go

参数	类型	必选	说明
FillerWordsConfig.Enable	*bool	否	是否启用承接词。默认值：false。
FillerWordsContent.Mode	*FillerWordsContentMode	是	承接词内容模式。动态模式使用 FillerWordsContentModeGenerated。
FillerWordsContentStaticConfig.Phrases	[]string	条件必填	配置静态回退时使用的短语列表。
FillerWordsContentGeneratedConfig	*FillerWordsContentGeneratedConfig	否	动态承接词配置。省略时使用服务端默认生成设置。
FillerWordsContentGeneratedConfig.Prompt	string	否	生成承接词的 Prompt。省略时使用默认 Prompt。

Python

参数	类型	必选	说明
enable	bool	否	是否启用承接词。默认值：False。
content.mode	str	是	设置为 generated，启用动态承接词。
content.static_config.phrases	List[str]	条件必填	配置静态回退时使用的短语列表。
content.generated_config	FillerWordsContentGeneratedConfig	否	动态承接词配置。省略时使用服务端默认生成设置。
content.generated_config.prompt	str	否	生成承接词的 Prompt。省略时使用默认 Prompt。
content.generated_config.fallback_strategy	str	否	回退策略。目前仅支持 static。

TypeScript

参数	类型	必选	说明
enable	boolean	否	是否启用承接词。默认值：false。
trigger.mode	string	否	承接词触发模式。默认值：fixed_time。
trigger.fixed_time_config.response_wait_ms	number	否	LLM 响应等待阈值，单位为毫秒。取值范围为 100 到 10000。默认值：1500。
content.mode	string	是	设置为 generated，启用动态承接词。
content.static_config.phrases	string[]	条件必填	配置静态回退时使用的短语列表。
content.generated_config	FillerWordsContentGeneratedConfig	否	动态承接词配置。省略时使用服务端默认生成设置。
content.generated_config.prompt	string	否	生成承接词的 Prompt。省略时使用默认 Prompt。
content.generated_config.fallback_strategy	string	否	回退策略。目前仅支持 static。

RESTful API

参数	类型	必选	说明
enable	Boolean	否	是否启用承接词。默认值：false。
trigger.mode	String	否	承接词触发模式。默认值：fixed_time。
trigger.fixed_time_config.response_wait_ms	Integer	否	LLM 响应等待阈值，单位为毫秒。取值范围为 100 到 10000。默认值：1500。
content.mode	String	是	设置为 generated，启用动态承接词。
content.static_config	Object	否	静态回退配置。动态承接词不可用时，可从该配置中选择静态承接词。
content.static_config.phrases	Array of String	条件必填	配置静态回退时的短语列表，支持 1 到 100 个非空字符串。
content.generated_config	Object	否	动态承接词配置。省略时使用默认 Prompt 和 static 回退策略。
content.generated_config.prompt	String	否	生成承接词的 Prompt。
content.generated_config.fallback_strategy	String	否	回退策略。目前仅支持 static。