护栏

为你的智能体实现安全检查和内容过滤

护栏通过在智能体执行的关键节点验证和过滤内容，帮助你构建安全、合规的 AI 应用。它们可以检测敏感信息、执行内容策略、验证输出，并在不安全行为造成问题之前加以阻止。

常见用例包括：

• 防止 PII（个人身份信息）泄露
• 检测和阻止提示词注入攻击
• 阻止不当或有害内容
• 执行业务规则和合规要求
• 验证输出质量和准确性

你可以使用中间件在关键位置拦截执行来实现护栏——在智能体启动之前、完成之后，或围绕模型和工具调用。

护栏可以使用两种互补的方法来实现：

确定性护栏

使用基于规则的逻辑，如正则表达式模式、关键词匹配或显式检查。快速、可预测且成本低，但可能遗漏细微的违规。

基于模型的护栏

使用 LLM 或分类器通过语义理解来评估内容。可以捕获规则遗漏的细微问题，但速度较慢且成本较高。

LangChain 提供了内置护栏（如 PII 检测、人机协作）以及灵活的中间件系统，用于使用任一方法构建自定义护栏。

内置护栏

PII 检测

LangChain 提供内置中间件，用于检测和处理对话中的个人身份信息（PII）。该中间件可以检测常见的 PII 类型，如电子邮件、信用卡、IP 地址等。

PII 检测中间件适用于具有合规要求的医疗和金融应用、需要清理日志的客户服务智能体，以及处理敏感用户数据的任何应用。

PII 中间件支持多种处理检测到的 PII 的策略：

策略	描述	示例
redact	替换为 [REDACTED_{PII_TYPE}]	[REDACTED_EMAIL]
mask	部分遮蔽（例如最后 4 位）	****-****-****-1234
hash	替换为确定性哈希	a8f5f167...
block	检测到时抛出异常	抛出错误

import { createAgent, piiRedactionMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [customerServiceTool, emailTool],
  middleware: [
    // 在发送到模型之前编辑用户输入中的电子邮件
    piiRedactionMiddleware({
      piiType: "email",
      strategy: "redact",
      applyToInput: true,
    }),
    // 遮蔽用户输入中的信用卡
    piiRedactionMiddleware({
      piiType: "credit_card",
      strategy: "mask",
      applyToInput: true,
    }),
    // 阻止 API 密钥——检测到时抛出错误
    piiRedactionMiddleware({
      piiType: "api_key",
      detector: /sk-[a-zA-Z0-9]{32}/,
      strategy: "block",
      applyToInput: true,
    }),
  ],
});

// 当用户提供 PII 时，将根据策略进行处理
const result = await agent.invoke({
  messages: [{
    role: "user",
    content: "My email is [e-mail] and card is 5105-1051-0510-5100"
  }]
});

内置 PII 类型和配置

内置 PII 类型：

• email - 电子邮件地址
• credit_card - 信用卡号码（经 Luhn 验证）
• ip - IP 地址
• mac_address - MAC 地址
• url - URL

配置选项：

参数	描述	默认值
piiType	要检测的 PII 类型（内置或自定义）	必填
strategy	如何处理检测到的 PII（"block"、"redact"、"mask"、"hash"）	"redact"
detector	自定义检测器正则表达式模式	undefined（使用内置）
applyToInput	在模型调用之前检查用户消息	true
applyToOutput	在模型调用之后检查 AI 消息	false
applyToToolResults	在执行后检查工具结果消息	false

有关 PII 检测功能的完整详情，请参阅中间件文档。

人机协作

LangChain 提供内置中间件，用于在执行敏感操作之前要求人工审批。这是高风险决策中最有效的护栏之一。

人机协作中间件适用于金融交易和转账、删除或修改生产数据、向外部方发送通信，以及任何具有重大业务影响的操作。

import { createAgent, humanInTheLoopMiddleware } from "langchain";
import { MemorySaver, Command } from "@langchain/langgraph";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, sendEmailTool, deleteDatabaseTool],
  middleware: [
    humanInTheLoopMiddleware({
      interruptOn: {
        // 敏感操作需要审批
        send_email: { allowAccept: true, allowEdit: true, allowRespond: true },
        delete_database: { allowAccept: true, allowEdit: true, allowRespond: true },
        // 安全操作自动批准
        search: false,
      }
    }),
  ],
  checkpointer: new MemorySaver(),
});

// 人机协作需要线程 ID 来持久化
const config = { configurable: { thread_id: "some_id" } };

// 智能体将在执行敏感工具之前暂停并等待审批
let result = await agent.invoke(
  { messages: [{ role: "user", content: "Send an email to the team" }] },
  config
);

result = await agent.invoke(
  new Command({ resume: { decisions: [{ type: "approve" }] } }),
  config  // 使用相同的线程 ID 来恢复暂停的对话
);

有关实现审批工作流的完整详情，请参阅人机协作文档。

自定义护栏

对于更复杂的护栏，你可以创建在智能体执行之前或之后运行的自定义中间件。这让你完全控制验证逻辑、内容过滤和安全检查。

智能体之前的护栏

使用”智能体之前”钩子在每次调用开始时验证请求一次。这对于会话级别的检查很有用，如认证、速率限制或在任何处理开始之前阻止不当请求。

import { createMiddleware, AIMessage } from "langchain";

const contentFilterMiddleware = (bannedKeywords: string[]) => {
  const keywords = bannedKeywords.map(kw => kw.toLowerCase());

  return createMiddleware({
    name: "ContentFilterMiddleware",
    beforeAgent: {
      hook: (state) => {
        // 获取第一条用户消息
        if (!state.messages || state.messages.length === 0) {
          return;
        }

        const firstMessage = state.messages[0];
        if (firstMessage._getType() !== "human") {
          return;
        }

        const content = firstMessage.content.toString().toLowerCase();

        // 检查禁用关键词
        for (const keyword of keywords) {
          if (content.includes(keyword)) {
            // 在任何处理之前阻止执行
            return {
              messages: [
                new AIMessage(
                  "I cannot process requests containing inappropriate content. Please rephrase your request."
                )
              ],
              jumpTo: "end",
            };
          }
        }

        return;
      },
      canJumpTo: ['end']
    }
  });
};

// 使用自定义护栏
import { createAgent } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, calculatorTool],
  middleware: [
    contentFilterMiddleware(["hack", "exploit", "malware"]),
  ],
});

// 此请求将在任何处理之前被阻止
const result = await agent.invoke({
  messages: [{ role: "user", content: "How do I hack into a database?" }]
});

智能体之后的护栏

使用”智能体之后”钩子在返回给用户之前验证最终输出一次。这对于基于模型的安全检查、质量验证或对完整智能体响应的最终合规扫描很有用。

import { createMiddleware, AIMessage, initChatModel } from "langchain";

const safetyGuardrailMiddleware = () => {
  const safetyModel = initChatModel("gpt-5.4-mini");

  return createMiddleware({
    name: "SafetyGuardrailMiddleware",
    afterAgent: {
      hook: async (state) => {
        // 获取最终 AI 响应
        if (!state.messages || state.messages.length === 0) {
          return;
        }

        const lastMessage = state.messages[state.messages.length - 1];
        if (lastMessage._getType() !== "ai") {
          return;
        }

        // 使用模型评估安全性
        const safetyPrompt = `Evaluate if this response is safe and appropriate.
        Respond with only 'SAFE' or 'UNSAFE'.

        Response: ${lastMessage.content.toString()}`;

        const result = await safetyModel.invoke([
          { role: "user", content: safetyPrompt }
        ]);

        if (result.content.toString().includes("UNSAFE")) {
          return {
            messages: [
              new AIMessage(
                "I cannot provide that response. Please rephrase your request."
              )
            ],
            jumpTo: "end",
          };
        }

        return;
      },
      canJumpTo: ['end']
    }
  });
};

// 使用安全护栏
import { createAgent } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, calculatorTool],
  middleware: [safetyGuardrailMiddleware()],
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "How do I make explosives?" }]
});

组合多个护栏

你可以通过将多个护栏添加到中间件数组来堆叠它们。它们按顺序执行，允许你构建分层保护：

import { createAgent, piiRedactionMiddleware, humanInTheLoopMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, sendEmailTool],
  middleware: [
    // 第 1 层：确定性输入过滤（智能体之前）
    contentFilterMiddleware(["hack", "exploit"]),

    // 第 2 层：PII 保护（模型之前和之后）
    piiRedactionMiddleware({
      piiType: "email",
      strategy: "redact",
      applyToInput: true,
    }),
    piiRedactionMiddleware({
      piiType: "email",
      strategy: "redact",
      applyToOutput: true,
    }),

    // 第 3 层：敏感工具的人工审批
    humanInTheLoopMiddleware({
      interruptOn: {
        send_email: { allowAccept: true, allowEdit: true, allowRespond: true },
      }
    }),

    // 第 4 层：基于模型的安全检查（智能体之后）
    safetyGuardrailMiddleware(),
  ],
});

其他资源

• 中间件文档 - 自定义中间件完整指南
• 中间件 API 参考 - 自定义中间件完整指南
• 人机协作 - 为敏感操作添加人工审查
• 测试智能体 - 安全机制测试策略

---

将这些文档连接到 Claude、VSCode 等工具，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交 issue。