安全护栏 - LangChain 文档

安全护栏通过在代理执行的关键点验证和过滤内容，帮助您构建安全、合规的 AI 应用程序。它们可以检测敏感信息，强制执行内容策略，验证输出，并防止不安全行为在造成问题之前发生。常见用例包括：

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

您可以使用中间件来实现安全护栏，在代理启动前、完成后或模型和工具调用时，在战略点拦截执行。

安全护栏可以通过两种互补的方法实现

确定性安全护栏

使用基于规则的逻辑，如正则表达式、关键字匹配或显式检查。快速、可预测且经济高效，但可能会遗漏细微的违规行为。

基于模型的安全护栏

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

LangChain 提供了内置安全护栏（例如，PII 检测、人工干预）和灵活的中间件系统，用于使用这两种方法构建自定义安全护栏。

内置安全护栏

PII 检测

LangChain 提供了内置中间件，用于检测和处理对话中的个人身份信息 (PII)。此中间件可以检测常见的 PII 类型，如电子邮件、信用卡、IP 地址等。 PII 检测中间件对于具有合规性要求的医疗保健和金融应用程序、需要清理日志的客户服务代理以及通常处理敏感用户数据的任何应用程序都很有帮助。 PII 中间件支持多种处理检测到的 PII 的策略：

策略	描述	示例
`编辑`	替换为 `[REDACTED_TYPE]`	`[REDACTED_EMAIL]`
`屏蔽`	部分遮盖（例如，最后 4 位数字）	`**--**-1234`
`哈希`	替换为确定性哈希	`a8f5f167...`
`阻止`	检测到时抛出异常	抛出错误

import { createAgent, piiRedactionMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-4o",
  tools: [customerServiceTool, emailTool],
  middleware: [
    // Redact emails in user input before sending to model
    piiRedactionMiddleware({
      piiType: "email",
      strategy: "redact",
      applyToInput: true,
    }),
    // Mask credit cards in user input
    piiRedactionMiddleware({
      piiType: "credit_card",
      strategy: "mask",
      applyToInput: true,
    }),
    // Block API keys - raise error if detected
    piiRedactionMiddleware({
      piiType: "api_key",
      detector: /sk-[a-zA-Z0-9]{32}/,
      strategy: "block",
      applyToInput: true,
    }),
  ],
});

// When user provides PII, it will be handled according to the strategy
const result = await agent.invoke({
  messages: [{
    role: "user",
    content: "My email is john.doe@example.com and card is 4532-1234-5678-9010"
  }]
});

内置 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-4o",
  tools: [searchTool, sendEmailTool, deleteDatabaseTool],
  middleware: [
    humanInTheLoopMiddleware({
      interruptOn: {
        // Require approval for sensitive operations
        send_email: { allowAccept: true, allowEdit: true, allowRespond: true },
        delete_database: { allowAccept: true, allowEdit: true, allowRespond: true },
        // Auto-approve safe operations
        search: false,
      }
    }),
  ],
  checkpointer: new MemorySaver(),
});

// Human-in-the-loop requires a thread ID for persistence
const config = { configurable: { thread_id: "some_id" } };

// Agent will pause and wait for approval before executing sensitive tools
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  // Same thread ID to resume the paused conversation
);

有关实施审批工作流的完整详细信息，请参阅人工干预文档。

自定义安全护栏

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

代理前安全护栏

使用“代理前”钩子在每次调用开始时验证请求。这对于会话级检查（如身份验证、速率限制或在任何处理开始之前阻止不当请求）很有用。

import { createMiddleware, AIMessage } from "langchain";

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

  return createMiddleware({
    name: "ContentFilterMiddleware",
    beforeAgent: (state) => {
      // Get the first user message
      if (!state.messages || state.messages.length === 0) {
        return;
      }

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

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

      // Check for banned keywords
      for (const keyword of keywords) {
        if (content.includes(keyword)) {
          // Block execution before any processing
          return {
            messages: [
              new AIMessage(
                "I cannot process requests containing inappropriate content. Please rephrase your request."
              )
            ],
            jumpTo: "end",
          };
        }
      }

      return;
    },
  });
};

// Use the custom guardrail
import { createAgent } from "langchain";

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

// This request will be blocked before any processing
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-4o-mini");

  return createMiddleware({
    name: "SafetyGuardrailMiddleware",
    afterAgent: async (state) => {
      // Get the final AI response
      if (!state.messages || state.messages.length === 0) {
        return;
      }

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

      // Use a model to evaluate safety
      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;
    },
  });
};

// Use the safety guardrail
import { createAgent } from "langchain";

const agent = createAgent({
  model: "gpt-4o",
  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-4o",
  tools: [searchTool, sendEmailTool],
  middleware: [
    // Layer 1: Deterministic input filter (before agent)
    contentFilterMiddleware(["hack", "exploit"]),

    // Layer 2: PII protection (before and after model)
    piiRedactionMiddleware({
      piiType: "email",
      strategy: "redact",
      applyToInput: true,
    }),
    piiRedactionMiddleware({
      piiType: "email",
      strategy: "redact",
      applyToOutput: true,
    }),

    // Layer 3: Human approval for sensitive tools
    humanInTheLoopMiddleware({
      interruptOn: {
        send_email: { allowAccept: true, allowEdit: true, allowRespond: true },
      }
    }),

    // Layer 4: Model-based safety check (after agent)
    safetyGuardrailMiddleware(),
  ],
});

附加资源

中间件文档 - 自定义中间件的完整指南
中间件 API 参考 - 自定义中间件的完整指南
人工干预 - 为敏感操作添加人工审查
测试代理 - 测试安全机制的策略

在 GitHub 上编辑此页面源文件。

以编程方式连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。

LangChain v1.0

入门

核心组件

高级用法

生产环境中使用

防护措施

确定性安全护栏

基于模型的安全护栏

内置安全护栏

PII 检测

人工干预

自定义安全护栏

代理前安全护栏

代理后安全护栏

组合多个安全护栏

附加资源

LangChain v1.0

入门

核心组件

高级用法

生产环境中使用

确定性安全护栏

基于模型的安全护栏

​内置安全护栏

​PII 检测

​人工干预

​自定义安全护栏

​代理前安全护栏

​代理后安全护栏

​组合多个安全护栏

​附加资源

内置安全护栏

PII 检测

人工干预

自定义安全护栏

代理前安全护栏

代理后安全护栏

组合多个安全护栏

附加资源