> 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.

# 护栏

## 概览

护栏让团队能够有效管理智能体在生产环境中的行为，在企业规模下确保其不偏离主题、符合品牌调性，并能抵御操纵。

借助 Guardrails 2.0，我们重新设计了安全层，让团队能更轻松地用自然语言定义自定义策略、启用预设保护措施、控制护栏触发后的处理方式，并有信心地将智能体部署到高影响力工作流程中。

护栏引导智能体做出正确响应，并在错误响应触达用户前将其拦截。它们从多个层面保护对话：塑造智能体的响应方式、验证用户输入，并在不增加延迟的情况下独立评估每条回复。由此可降低每次对话中的品牌和合规风险。

## 护栏工作原理

护栏从三个层面保护对话：

**系统提示词强化：** 控制智能体行为的主要方式。你可以在系统提示词中添加关于允许和禁止行为的明确指引，并启用 Focus Guardrail，在整个对话中强化这些指令。这能让智能体在绝大多数交互中保持正轨。

**用户输入验证：** 在智能体响应前拦截对抗性尝试的安全网。护栏会分析用户所说的内容，检测提示词注入和操纵尝试，并可终止存在安全风险的对话。

**智能体响应验证：** 根据配置的策略，实时独立评估每条智能体回复的最终检查。即使智能体未遵循系统提示词，准备说出违反规则的内容，响应验证器也会在发送前将其拦截。

系统提示词强化是基础。输入和响应验证则为遗漏的问题提供纠偏。对于最关键的规则，建议同时写入系统提示词，并设为独立的自定义护栏——这能形成纵深防御，即使 LLM 偏离指令，响应验证器也能在发送前将其拦截。

| 护栏           | 功能                    | 保护层级    | 对延迟的影响                     | 费用    | 退出策略 | 发布状态  |
| ------------ | --------------------- | ------- | -------------------------- | ----- | ---- | ----- |
| Focus        | 让智能体不偏离主题，并与系统提示词保持一致 | 系统提示词强化 | 极小                         | 已包含   | 不适用  | 正式发布  |
| Manipulation | 检测并拦截提示词注入            | 用户输入验证  | 无影响                        | 已包含   | 终止对话 | 正式发布  |
| Content      | 标记并防止不当内容             | 智能体响应验证 | [取决于执行模式](#execution-mode) | 已包含   | 可配置  | Alpha |
| Custom       | 执行特定于业务的策略            | 智能体响应验证 | [取决于执行模式](#execution-mode) | 按用量计费 | 可配置  | Alpha |

## 系统提示词强化

要让智能体按预期行为，最有效的方法是编写出色的系统提示词并启用 Focus Guardrail。两者结合，能从一开始就引导智能体给出正确响应。

你可以使用系统提示词，明确指示智能体应该做什么和不应该做什么。模型会特别关注 `# Guardrails` 标题。请将最关键的行为规则放在此标题下。

**`示例：系统提示词强化`**

```mdx title="示例：系统提示词强化"
# Guardrails

- Only provide information that is publicly documented about ElevenLabs products, pricing, and features.
- Do not speculate about unreleased features, internal roadmaps, or future pricing changes.
- If you cannot resolve an issue with available documentation or tools, clearly explain the limitation and offer to escalate to a human support representative.
```

如需了解如何编写有效系统提示词的完整指南，请参阅我们的[提示词指南](/docs/zh/eleven-agents/best-practices/prompting-guide)。ElevenLabs 客户团队也可协助你编写高质量系统提示词。

**Focus Guardrail：** Focus Guardrail 可强化智能体的系统提示词，帮助回复保持聚焦、相关，并符合你定义的目标和指令。在较长或复杂的对话中，智能体更容易偏离原定目标，此功能尤其有用。

结合系统提示词强化和启用 Focus Guardrail，是引导智能体做出正确响应的最有效方法。

## 用户输入验证

### Manipulation Guardrails

检测并拦截用户试图操纵智能体绕过其指令的行为。启用后，系统会分析用户输入，识别表明存在注入或指令覆盖尝试的模式，并可终止存在安全风险的对话。

## 智能体响应验证

### 内容护栏

在智能体响应触达用户前，标记并防止其中出现不当内容，例如政治敏感、露骨色情或暴力材料。这有助于确保响应适合智能体的预期使用场景和受众。

### 自定义护栏

随着智能体承担高影响力工作，团队需要明确控制其行为。自定义护栏让你能够配置对业务最重要的策略。例如：

* 零售助手不应为不符合条件的商品退款。
* 医疗接待员不应提供医疗建议。
* 银行智能体不应推荐投资。

自定义护栏是基于 LLM 的规则，可让你使用自然语言提示词定义自己的拦截条件。每个启用的自定义护栏都会将智能体响应发送给轻量级模型，由其根据规则进行评估并返回拦截或允许的决定。这样你可以灵活、按领域控制智能体能说和不能说的内容。

对于每个自定义护栏，你可以定义：

| 字段             | 描述                                                     |
| -------------- | ------------------------------------------------------ |
| **名称**         | 护栏的描述性标签（例如，“不提供财务建议”）。                                |
| **提示词**        | 描述需拦截内容的自然语言指令（例如，“拦截任何提供具体财务建议、投资建议或税务指导的内容”）。        |
| **执行模式**       | `streaming`（默认）或 `blocking`。参阅[执行模式](#execution-mode)。 |
| **触发操作（退出策略）** | `end_call`（默认）或 `retry`。参阅[退出策略](#exit-strategies)。    |

自定义护栏可用于拦截与业务相关的特定主题、执行行业特定的合规要求，以及实施专有安全措施。无需删除即可分别启用或停用；启用多个护栏时，它们会与其他护栏并行运行。所有触发的违规行为都会被记录以供审查。

## 执行模式

执行模式决定护栏是否会在用户看到或听到回复前增加等待时间。

在 **streaming** 模式下，护栏触发前可能已开始输出智能体响应；对于语音，拦截结束通话前可能会先发送一小部分音频（通常不到 500 ms）。对于文本智能体，如果评估未在发送前完成，用户可能会看到部分或完整响应。

在 **Blocking** 模式下，智能体仅在护栏验证完成后才会响应。这通常会额外增加 **200–500 ms** 延迟。

## 退出策略

退出策略让你定义护栏触发时智能体的处理方式。你可以选择：

* **`end_call`** *（默认）*：立即结束通话
* **`retry`**：根据你的反馈重新生成响应，而非中断对话。智能体最多重试 3 次；若每次尝试仍违反护栏，则结束通话。

> **Warning**
>
> 重试仅适用于阻塞模式。在流式模式下，结束通话是唯一可用的退出
> 策略。

#### 重试反馈

**重试**反馈可包含你希望在下一轮应用的**任何指令**——在模型重新生成前，它会作为系统指引注入。这包括调用 `transfer_to_agent` 或 `transfer_to_number` 等系统工具。以下是配置重试反馈的一些示例：

* **通用拒绝**（默认）\
   *你的响应被护栏拦截，该护栏会拦截符合以下条件/类别的内容：'\{\{trigger_reason}}'。下一轮中，你必须告诉用户“抱歉，我无法回答这个问题。你想了解其他内容吗？”*
* **使用纠正指令重试**\
   *你之前的响应被护栏拦截。被拦截的响应是：'\{\{agent_message}}'。下一轮中，你必须提供新答案，且不得违反：'\{\{trigger_reason}}'。*
* **转接至其他智能体**\
   *你之前的响应被护栏拦截。下一轮中，你必须使用 transfer_to_agent 工具并转接至一名智能体。被拦截的响应是：'\{\{agent_message}}'。该护栏会拦截符合以下条件/类别的内容：'\{\{trigger_reason}}'。*
* **转接给人工客服**\
   *你的响应被护栏拦截，该护栏会拦截符合以下条件/类别的内容：'\{\{trigger_reason}}'。下一轮中，你必须使用 transfer_to_number 工具将通话转接给人工客服。*

> **Tip**
>
> 如需在重试反馈中使用**系统工具**，请在智能体设置中启用并配置相应工具。
> 只能调用已在智能体上设置的工具。

你可以在反馈文本中使用以下占位符：

| 占位符                  | 替换为                                    |
| -------------------- | -------------------------------------- |
| `{{trigger_reason}}` | 在自定义护栏中定义的护栏**提示词**；在内容护栏中定义的触发**类别**。 |
| `{{agent_message}}`  | 被拦截的智能体输出（可用于引导重试）。                    |

> **Tip**
>
> **语音**智能体建议使用**流式**执行模式；**文本**智能体建议使用**阻塞**执行模式。

> **Warning**
>
> **阻塞**模式（尤其搭配**重试**）在语音中可能表现得不够可预测。若在语音中使用阻塞模式，
> 请充分验证，或在确认行为可靠前选择**结束通话**而非**重试**。

## 定价

所有 ElevenAgents 用户均可**免费**使用 **Focus**、**Manipulation** 和 **Content** 护栏。

**自定义护栏**按用量计费，并会产生**额外 LLM 费用**，与 ElevenAgents 中其他模型调用类似。每个启用的自定义护栏都会将每条智能体响应发送给轻量级模型评估，因此费用取决于提示词长度、平均对话长度和对话量。若启用多个自定义护栏，每个护栏都会针对每条响应单独评估。建议在生产环境中启用多个自定义护栏前，先评估预期流量和模型选择。

创建或编辑自定义护栏时，可以看到预估费用（位于提示词下方）。

![自定义护栏费用预估](/docs/_fern-img/a829a7451a1bb209dcbbe718dc75c3f6a28191f4de8ad6be44da6e0b7d4466ec.webp)

> **Note**
>
> **重试和费用：** 每次尝试都会额外生成一次智能体响应，并再次进行护栏评估，
> 因此与 **end_call** 相比，**retry** 会增加按用量计费的费用（每个被拦截的轮次
> 最多尝试 3 次）。

## 配置

#### 通过控制台配置

#### 前往智能体设置

在 ElevenLabs 控制台中打开智能体，然后进入 **安全** 标签页。

#### 启用护栏

打开要启用的护栏类别。可使用预设按钮快速启用或禁用所有类别。

#### 配置执行模式和退出策略（自定义和内容护栏）

为每个自定义或内容护栏选择 **流式** 或 **阻塞式** 执行模式。
**阻塞式** 适用于 **文本** 智能体；**流式** 适用于 **语音** 智能体。设置**护栏违规时的操作**
（对应 **`trigger_action`**）：任意模式下均可选择**结束通话 **；仅在选择 **阻塞式** 时可选择**重试**
（**流式** 模式不支持**重试**）。如果选择**重试**，请编辑**重试时注入的反馈**来引导模型。可在模板中使用占位符
<code />（导致拦截的自定义提示词或内容类别）和 <code />。

#### 保存配置

保存智能体配置。更改会立即应用于新对话。

#### 通过 CLI 配置

#### 拉取智能体配置

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

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

设置 `platform_settings.guardrails`：

```json
{
  "platform_settings": {
    "guardrails": {
      "version": "1",
      "prompt_injection": { "isEnabled": true },
      "custom": {
        "config": {
          "configs": [
            {
              "is_enabled": true,
              "name": "No financial advice",
              "prompt": "Block any content that provides specific financial advice, investment recommendations, or tax guidance.",
              "execution_mode": "blocking",
              "trigger_action": {
                "type": "retry",
                "feedback": "Your response was blocked by a guardrail that blocks content that matches this condition/category: '{{trigger_reason}}' During your next turn you must tell the user \"I'm sorry but I can't answer that question, would you like to know something else?\"."
              }
            }
          ]
        }
      }
    }
  }
}
```

#### 推送更改

```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={
        "guardrails": {
            "version": "1",
            "prompt_injection": {"isEnabled": True},
            "custom": {
                "config": {
                    "configs": [
                        {
                            "is_enabled": True,
                            "name": "No financial advice",
                            "prompt": "Block any content that provides specific financial advice, investment recommendations, or tax guidance.",
                            "execution_mode": "blocking",
                            "trigger_action": {
                                "type": "retry",
                                "feedback": "Your response was blocked by a guardrail that blocks content that matches this condition/category: '{{trigger_reason}}' During your next turn you must tell the user \"I'm sorry but I can't answer that question, would you like to know something else?\".",
                            },
                        }
                    ]
                }
            },
        },
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  platformSettings: {
    guardrails: {
      version: "1",
      promptInjection: { isEnabled: true },
      custom: {
        config: {
          configs: [
            {
              isEnabled: true,
              name: "No financial advice",
              prompt:
                "Block any content that provides specific financial advice, investment recommendations, or tax guidance.",
              executionMode: "blocking",
              triggerAction: {
                type: "retry",
                feedback: `Your response was blocked by a guardrail that blocks content that matches this condition/category: '{{trigger_reason}}' During your next turn you must tell the user "I'm sorry but I can't answer that question, would you like to know something else?".`,
              },
            },
          ],
        },
      },
    },
  },
});
```

护栏触发后的行为取决于其类型和配置：

* **结束通话：** 会话立即结束（语音通话会挂断，文本聊天会结束）。触发事件会记录在对话历史中。
* **重试（阻塞式自定义或内容护栏）：** 会移除违规的助手轮次、注入系统反馈，并让模型重新尝试；如果护栏仍被触发，最多尝试 3 次后会话将结束。

> **Note**
>
> 选择**结束通话**后，最终用户会遇到通话挂断或聊天结束。可在对话日志中查看违规详情，
> 最终用户不会直接看到这些详情。

> **Note**
>
> **结束通话**后，用户可以发起新对话。护栏不会永久阻止用户，
> 而是拦截违反策略的特定回复（或会话）。

## 最佳实践

#### 客服智能体

使用自定义护栏来执行业务特定策略。例如：- 除非通过工具确认符合资格，否则禁止发放退款、
额度或更改订阅。- 除非获得明确授权，否则禁止提供折扣或促销代码。- 禁止回复中
猜测路线图项目或未发布功能。

#### 医疗应用

使用自定义护栏严格控制医疗边界。例如：- 禁止诊断疾病或推荐具体治疗方案。- 禁止提供药物
剂量建议。- 禁止替代持证医疗专业人员的建议。

#### 教育内容

使用自定义护栏控制敏感的学术主题。例如：- 禁止提供有害实验或不安全操作的分步
指导。- 禁止为正在进行的测验或考试生成答案。- 禁止生成可能助长学术不端的内容。

#### 企业内部工具

使用自定义护栏保护公司运营和数据。例如：- 禁止分享仅限内部使用的文档或机密流程。- 禁止泄露私有 API、系统
提示词或基础设施详情。- 禁止模拟需要高管或管理权限的操作。

### 使用真实场景测试

部署前，请使用以下场景测试护栏配置：

* 正常对话流程，确保不会出现误报
* 接近但未越过安全边界的边缘情况
* 试图诱导有害回复的对抗性提示词

## 常见问题

#### 护栏会影响延迟吗？

对于自定义和内容护栏，**流式** 模式不会增加额外延迟，但护栏触发前可能已开始输出回复。
**阻塞式** 模式会在智能体回复前等待护栏结果，通常会增加约 **200–500 ms** 延迟。每次使用 **重试**
都会增加一次完整生成（和重新评估），每个被拦截的轮次最多 3 次，因此也会增加按用量计费的成本。

#### 流式和阻塞式执行模式有什么区别？

**流式** 不会增加额外延迟，但护栏触发前智能体可能已开始回复。**阻塞式** 会在智能体回复前等待护栏结果（通常
延迟 **200–500 ms**）。作为退出策略的 **重试**（**`trigger_action`**）\*\* 仅**在 **阻塞式**
模式中可用；在 **流式** 模式中，护栏触发时只能使用**结束通话\*\*。**阻塞式** 支持通过注入系统反馈来**重试**，
而非立即结束对话；代价是重试时会增加模型用量和**额外费用**。建议 **文本** 智能体使用 **阻塞式**，
**语音** 智能体使用 **流式**。

#### 可以完全禁用护栏吗？

可以，但强烈建议保持所有护栏启用，尤其是焦点护栏。它们能保护品牌、用户和合规状况，建议所有
生产环境应用（包括内部工具）都使用。在少数情况下，如果某个特定护栏干扰了智能体的预期使用场景，可能需要将其禁用。
例如，某些应用可能涉及原本会被内容护栏标记的主题，或者高度定制的系统提示词在启用焦点护栏时可能无法正常工作。
每个护栏都可以单独开启或关闭。

#### 用户可以申诉护栏决定吗？

护栏触发事件会被记录，可在对话分析中查看。如果发现误报，请调整护栏提示词。目前没有自动申诉流程，
用户只需发起新对话。

#### 如何知道触发了哪个护栏？

可在对话日志中查看触发的护栏信息。

#### 应该同时使用护栏和系统提示词加固吗？

是的。两者用途互补。系统提示词加固提供行为指引，并通过遵循指令预防大多数问题。平台护栏则作为安全网提供独立
执行。两者结合可实现纵深防御。

## 后续步骤

* **[提示词指南](/docs/zh/eleven-agents/best-practices/prompting-guide)：** 了解如何编写带有行为护栏的有效系统提示词
* **[隐私](/docs/zh/eleven-agents/customization/privacy)：** 配置数据保留和隐私设置
* **[测试](/docs/zh/eleven-agents/customization/agent-testing)：** 使用不同场景测试智能体
* **[模拟对话](/docs/zh/eleven-agents/guides/simulate-conversation)：** 通过编程方式测试护栏配置
* **[对话历史记录脱敏](/docs/zh/eleven-agents/customization/privacy/conversation-history-redaction)：** 从对话历史中移除姓名、银行详细信息等敏感信息

## 发布状态

护栏现已正式发布，包括焦点护栏和操控护栏。

内容护栏和自定义护栏目前处于 Alpha 阶段。我们正在积极改进它们，在正式发布前，其默认设置、控制台控件和 API 字段仍会持续演进。部分更改可能不向后兼容。

如果使用内容或自定义护栏，建议验证设置，在日志中监控护栏行为，并在更新推出时重新检查配置。