覆盖项 | ElevenLabs Documentation

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

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

概述

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

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

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

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

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

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 更新

前往智能体设置并选择安全标签页。启用 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 模型字符串，请参阅智能体 API 参考文档，其中列出了所有受支持的 LLM 模型及其准确的字符串标识符。