覆盖设置 | ElevenLabs Documentation

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

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

概览

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

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

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

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

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

以下是几个适合使用覆盖设置的场景：

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

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

指南

前提条件

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

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

启用覆盖设置

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

通过控制台更新

通过 CLI 更新

通过 API 更新

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

覆盖对话设置

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

对话启动负载

{
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "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.
            "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 模型字符串，请参阅列出所有受支持 LLM 模型及其准确字符串标识符的智能体 API 参考文档。