覆盖设置 | ElevenLabs Documentation

虽然覆盖设置仍支持完全替换系统提示词或首条消息，但建议使用动态变量作为定制智能体回复和注入实时数据的首选方式。动态变量更易维护，也提供了更结构化的个性化方法。

覆盖设置让助手能够针对每次用户互动调整行为。你可以在每次对话开始时传入自定义数据和设置，让助手利用实时上下文个性化回复和知识。覆盖设置会完全覆盖智能体控制台中定义的默认值。

概览

无需创建多个智能体，覆盖设置即可实时修改 AI 智能体的行为，从而使用用户专属数据个性化回复。

可在智能体安全设置中为以下字段启用覆盖设置：

系统提示词
首条消息
语言
语音 ID
LLM（大语言模型）
LLM 推理强度
工具
知识库
纯文本模式
稳定性
速度
相似度增强
ASR 关键词
流程

流程覆盖设置不使用 conversation_config_override。客户端会在对话初始化客户端数据的顶层传入 procedure_ids 和 start_procedure_ids。参见为每次对话选择流程。

为某个字段启用覆盖设置后，是否提供覆盖值仍是可选的。如未提供，智能体将使用其控制台中定义的默认值。对于大多数字段，如果该字段未启用覆盖设置却提供了覆盖值，将会报错。

ASR 关键词采用软性禁用：如果安全开关处于关闭状态，而客户端仍发送 asr.keywords，对话会继续进行，但会忽略这些关键词（不报错）。如需将每次对话的关键词增强应用到对话中，请在安全设置中启用 ASR 关键词 覆盖设置。每次对话最多支持 50 个关键词。

推理强度必须是智能体 LLM 支持的级别。否则对话不会启动，连接将关闭并显示不受支持级别的错误。如果安全开关处于关闭状态，prompt.reasoning_effort 会被忽略，并使用智能体已保存的推理强度。该值在整个对话期间固定，开始后无法更改。

以下是一些适合使用覆盖设置的场景：

按姓名问候用户
在回复中包含账户专属信息
根据用户偏好调整智能体语言或语气
传入实时数据，例如账户余额或订单状态
通过 ASR 关键词增强每通电话中姓名或术语（例如 CRM 公司名称）的转写效果

对于需要个性化互动，或处理不应存储在智能体基础配置中的敏感用户数据的应用，覆盖设置尤其有用。

指南

前提条件

一个 ElevenLabs 账户
已配置的 ElevenLabs 对话式智能体（在此创建）

本指南将介绍如何覆盖智能体默认的系统提示词、首条消息、LLM、推理强度、工具、知识库、TTS 设置和 ASR 关键词。

启用覆盖设置

出于安全考虑，覆盖设置默认处于禁用状态。启用允许覆盖的字段，例如 first_message、prompt.prompt、prompt.reasoning_effort、prompt.tool_ids、prompt.knowledge_base、language 或 asr.keywords。

通过控制台更新

通过 CLI 更新

通过 API 更新

前往智能体设置并选择安全标签页。启用 First message、System prompt、Tools、Knowledge base、ASR keywords 及其他所需的覆盖设置，例如 LLM 或 Reasoning effort。

覆盖对话设置

在启动对话的代码中，将覆盖设置作为参数传入。工具和知识库覆盖设置会替换该次对话的默认数组。ASR 关键词覆盖设置会替换该次对话的智能体默认关键词列表（最多 50 个关键词）。

对话初始化载荷

{
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "reasoning_effort": "high",
        "tool_ids": ["tool_7101k5zvyjhmfg983brhmhkd98n6"],
        "knowledge_base": [
          {
            "type": "file",
            "name": "Unladen Swallow Facts",
            "id": "5xM3yVvZQKV0EfqQpLrJ",
            "usage_mode": "auto"
          }
        ]
      }
    },
    "asr": {
      "keywords": ["Acme Corp", "Contoso", "Globex"]
    }
  }
}

请确保已安装最新版 SDK。

from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
...
conversation_override = {
    "agent": {
        "prompt": {
            "prompt": f"The customer's bank account balance is {customer_balance}. They are based in {customer_location}.", # Optional: override the system prompt.
            "llm": "gpt-4o", # Optional: override the LLM model.
            "reasoning_effort": "high", # Optional: override the reasoning effort. Requires Security → Reasoning effort.
            "tool_ids": [
                "tool_7101k5zvyjhmfg983brhmhkd98n6"
            ], # Optional: replace the tools available to the agent.
            "knowledge_base": [
                {
                    "type": "file",
                    "name": "Unladen Swallow Facts",
                    "id": "5xM3yVvZQKV0EfqQpLrJ",
                    "usage_mode": "auto",
                }
            ], # Optional: replace the knowledge base available to the agent.
        },
        "first_message": f"Hi {customer_name}, how can I help you today?", # Optional: override the first_message.
        "language": "en" # Optional: override the language.
    },
    "tts": {
        "voice_id": "custom_voice_id", # Optional: override the voice.
        "stability": 0.7, # Optional: override stability (0.0 to 1.0).
        "speed": 1.1, # Optional: override speed (0.7 to 1.2).
        "similarity_boost": 0.9 # Optional: override similarity boost (0.0 to 1.0).
    },
    "conversation": {
        "text_only": True # Optional: enable text-only mode (no audio).
    },
    "asr": {
        "keywords": ["Acme Corp", "Contoso"] # Optional: boost ASR for per-call terms (max 50). Requires Security → ASR keywords.
    }
}
config = ConversationInitiationData(
    conversation_config_override=conversation_override
)
conversation = Conversation(
    ...
    config=config,
    ...
)
conversation.start_session()

使用覆盖设置时，请省略不想覆盖的字段，不要将其设为空字符串或 null 值。仅包含需要定制的字段。

要查找正确的 LLM 模型字符串，请参阅智能体 API 参考文档，其中列出了所有支持的 LLM 模型及其准确的字符串标识符。