> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 覆盖设置

> **Warning**
>
> 虽然覆盖设置仍支持完全替换系统提示词或首条消息，但建议使用[动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)，这是自定义智能体回复和注入实时数据的首选方式。动态变量更易维护，也提供了更结构化的个性化方式。

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

## 概览

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

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

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

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

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

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

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

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

## 指南

### 前提条件

* [ElevenLabs 账户](https://elevenlabs.io)
* 已配置的 ElevenLabs 对话式智能体（[在此创建](/docs/zh/eleven-agents/quickstart)）

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

#### 启用覆盖设置

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

#### 通过控制台更新

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

![启用覆盖设置](/docs/_fern-img/496f20380ffe29fc46275bbfe5c6eaabdb5e211c780188243a018b38715ea779.webp)

#### 通过 CLI 更新

#### 拉取智能体配置

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### 编辑 \`agent_configs/\<agent-name>.json\`

将 `platform_settings.overrides.conversation_config_override` 下的字段设为 `true`，以允许在运行时覆盖该字段：

```json
{
  "platform_settings": {
    "overrides": {
      "conversation_config_override": {
        "agent": {
          "first_message": true,
          "language": true,
          "prompt": {
            "prompt": true,
            "tool_ids": true,
            "knowledge_base": true
          }
        },
        "tts": { "voice_id": true },
        "asr": { "keywords": true }
      }
    }
  }
}
```

#### 推送更改

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### 通过 API 更新

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    platform_settings={
        "overrides": {
            "conversation_config_override": {
                "agent": {
                    "first_message": True,
                    "language": True,
                    "prompt": {
                        "prompt": True,
                        "tool_ids": True,
                        "knowledge_base": True,
                    },
                },
                "tts": {"voice_id": True},
                "asr": {"keywords": True},
            },
        },
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  platformSettings: {
    overrides: {
      conversationConfigOverride: {
        agent: {
          firstMessage: true,
          language: true,
          prompt: {
            prompt: true,
            toolIds: true,
            knowledgeBase: true,
          },
        },
        tts: { voiceId: true },
        asr: { keywords: true },
      },
    },
  },
});
```

#### 覆盖对话设置

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

**`对话启动负载`**

```json title="对话启动负载" focus={4-15}
{
  "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"]
    }
  }
}
```

> **Tip**
>
> 请确保已安装最新版 [SDK](/docs/zh/eleven-agents/libraries/python)。

**`Python`**

```python title="Python" focus={3-28} maxLines=28
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()
```

**`JavaScript`**

```javascript title="JavaScript" focus={4-29} maxLines=29
...
const conversation = await Conversation.startSession({
  ...
  overrides: {
      agent: {
          prompt: {
              prompt: `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.
              toolIds: [
                  "tool_7101k5zvyjhmfg983brhmhkd98n6"
              ], // Optional: replace the tools available to the agent.
              knowledgeBase: [
                  {
                      type: "file",
                      name: "Unladen Swallow Facts",
                      id: "5xM3yVvZQKV0EfqQpLrJ",
                      usageMode: "auto",
                  }
              ], // Optional: replace the knowledge base available to the agent.
          },
          firstMessage: `Hi ${customer_name}, how can I help you today?`, // Optional: override the first message.
          language: "en" // Optional: override the language.
      },
      tts: {
          voiceId: "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).
          similarityBoost: 0.9 // Optional: override similarity boost (0.0 to 1.0).
      },
      conversation: {
          textOnly: 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.
      }
  },
  ...
})
```

**`Swift`**

```swift title="Swift" focus={3-16} maxLines=16
import ElevenLabsSDK

let promptOverride = ElevenLabsSDK.AgentPrompt(
    prompt: "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.
)
let agentConfig = ElevenLabsSDK.AgentConfig(
    prompt: promptOverride, // Optional: override the system prompt.
    firstMessage: "Hi \(customer_name), how can I help you today?", // Optional: override the first message.
    language: .en // Optional: override the language.
)
let ttsConfig = ElevenLabsSDK.TTSConfig(
    voiceId: "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).
    similarityBoost: 0.9 // Optional: override similarity boost (0.0 to 1.0).
)
let conversationConfig = ElevenLabsSDK.ConversationConfig(
    textOnly: true // Optional: enable text-only mode (no audio).
)
let overrides = ElevenLabsSDK.ConversationConfigOverride(
    agent: agentConfig, // Optional: override agent settings.
    tts: ttsConfig, // Optional: override TTS settings.
    conversation: conversationConfig // Optional: override conversation settings.
)

let config = ElevenLabsSDK.SessionConfig(
    agentId: "",
    overrides: overrides
)

let conversation = try await ElevenLabsSDK.Conversation.startSession(
  config: config,
  callbacks: callbacks
)
```

**`Widget`**

```html title="Widget"
  <elevenlabs-convai
    agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
    override-language="es"         <!-- Optional: override the language -->
    override-prompt="Custom system prompt for this user"  <!-- Optional: override the system prompt -->
    override-first-message="Hi! How can I help you today?"  <!-- Optional: override the first message -->
    override-voice-id="custom_voice_id"  <!-- Optional: override the voice -->
  ></elevenlabs-convai>
```

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

> **Tip**
>
> 要查找正确的 LLM 模型字符串，请参阅列出所有受支持 LLM 模型及其准确字符串标识符的[智能体 API 参考文档](/docs/zh/api-reference/agents/create#request.body.conversation_config.agent.prompt.llm)。