护栏 - Docs by LangChain中文

护栏通过在代理执行的关键点验证和过滤内容，帮助您构建安全、合规的 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`	检测到时抛出异常	抛出错误

当设置 apply_to_output=True 时，PIIMiddleware 也会通过注册的流转换器对流式线输出进行编辑——包括文本增量、工具调用参数、工具输出和状态快照。需要 langchain>=1.3.2。参见在中间件上注册转换器。

from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware


agent = create_agent(
    model="gpt-5.5",
    tools=[customer_service_tool, email_tool],
    middleware=[
        # 在发送给模型之前编辑用户输入中的电子邮件
        PIIMiddleware(
            "email",
            strategy="redact",
            apply_to_input=True,
        ),
        # 在用户输入中掩码信用卡信息
        PIIMiddleware(
            "credit_card",
            strategy="mask",
            apply_to_input=True,
        ),
        # 阻止 API 密钥 - 如果检测到则抛出错误
        PIIMiddleware(
            "api_key",
            detector=r"sk-[a-zA-Z0-9]{32}",
            strategy="block",
            apply_to_input=True,
        ),
    ],
)

# 当用户提供 PII 时，将根据策略进行处理
result = agent.invoke({
    "messages": [{"role": "user", "content": "My email is john.doe@example.com and card is 5105-1051-0510-5100"}]
})

内置 PII 类型与配置

内置 PII 类型：

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

配置选项：

参数	描述	默认值
`pii_type`	要检测的 PII 类型（内置或自定义）	必填
`strategy`	如何处理检测到的 PII (`"block"`, `"redact"`, `"mask"`, `"hash"`)	`"redact"`
`detector`	自定义检测器函数或正则表达式模式	`None`（使用内置检测器）
`apply_to_input`	在模型调用前检查用户消息	`True`
`apply_to_output`	在模型调用后检查 AI 消息	`False`
`apply_to_tool_results`	在执行后检查工具结果消息	`False`

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

人机协作

LangChain 提供了在执行敏感操作前需要人工批准的内置中间件。这是针对高风险决策最有效的护栏之一。人机协作中间件适用于以下场景：金融交易和转账、删除或修改生产数据、向外部方发送通信，以及任何具有重大业务影响的操作。

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command


agent = create_agent(
    model="gpt-5.5",
    tools=[search_tool, send_email_tool, delete_database_tool],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                # 敏感操作需要批准
                "send_email": True,
                "delete_database": True,
                # 安全操作自动批准
                "search": False,
            }
        ),
    ],
    # 在中断间持久化状态
    checkpointer=InMemorySaver(),
)

# 人机协作需要线程 ID 以实现持久化
config = {"configurable": {"thread_id": "some_id"}}

# 代理将暂停并在执行敏感工具前等待批准
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Send an email to the team"}]},
    config=config
)

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

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

自定义护栏

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

代理前护栏

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

from typing import Any

from langchain.agents.middleware import AgentMiddleware, AgentState, hook_config
from langgraph.runtime import Runtime

class ContentFilterMiddleware(AgentMiddleware):
    """确定性护栏：阻止包含禁用关键字的请求。"""

    def __init__(self, banned_keywords: list[str]):
        super().__init__()
        self.banned_keywords = [kw.lower() for kw in banned_keywords]

    @hook_config(can_jump_to=["end"])
    def before_agent(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
        # 获取第一条用户消息
        if not state["messages"]:
            return None

        first_message = state["messages"][0]
        if first_message.type != "human":
            return None

        content = first_message.content.lower()

        # 检查禁用关键字
        for keyword in self.banned_keywords:
            if keyword in content:
                # 在任何处理之前阻止执行
                return {
                    "messages": [{
                        "role": "assistant",
                        "content": "I cannot process requests containing inappropriate content. Please rephrase your request."
                    }],
                    "jump_to": "end"
                }

        return None

# 使用自定义护栏
from langchain.agents import create_agent

agent = create_agent(
    model="gpt-5.5",
    tools=[search_tool, calculator_tool],
    middleware=[
        ContentFilterMiddleware(
            banned_keywords=["hack", "exploit", "malware"]
        ),
    ],
)

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

from typing import Any

from langchain.agents.middleware import before_agent, AgentState, hook_config
from langgraph.runtime import Runtime

banned_keywords = ["hack", "exploit", "malware"]

@before_agent(can_jump_to=["end"])
def content_filter(state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
    """确定性护栏：阻止包含禁用关键字的请求。"""
    # 获取第一条用户消息
    if not state["messages"]:
        return None

    first_message = state["messages"][0]
    if first_message.type != "human":
        return None

    content = first_message.content.lower()

    # 检查禁用关键字
    for keyword in banned_keywords:
        if keyword in content:
            # 在任何处理之前阻止执行
            return {
                "messages": [{
                    "role": "assistant",
                    "content": "I cannot process requests containing inappropriate content. Please rephrase your request."
                }],
                "jump_to": "end"
            }

    return None

# 使用自定义护栏
from langchain.agents import create_agent

agent = create_agent(
    model="gpt-5.5",
    tools=[search_tool, calculator_tool],
    middleware=[content_filter],
)

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

代理后护栏

使用“代理后”钩子在返回给用户之前对最终输出进行一次验证。这对于基于模型的安全检查、质量验证或对完整代理响应进行最终合规性扫描非常有用。

from langchain.agents.middleware import AgentMiddleware, AgentState, hook_config
from langgraph.runtime import Runtime
from langchain.messages import AIMessage
from langchain.chat_models import init_chat_model
from typing import Any

class SafetyGuardrailMiddleware(AgentMiddleware):
    """基于模型的护栏：使用 LLM 评估响应安全性。"""

    def __init__(self):
        super().__init__()
        self.safety_model = init_chat_model("gpt-5.4-mini")

    @hook_config(can_jump_to=["end"])
    def after_agent(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
        # 获取最终的 AI 响应
        if not state["messages"]:
            return None

        last_message = state["messages"][-1]
        if not isinstance(last_message, AIMessage):
            return None

        # 使用模型评估安全性
        safety_prompt = f"""Evaluate if this response is safe and appropriate.
        Respond with only 'SAFE' or 'UNSAFE'.

        Response: {last_message.content}"""

        result = self.safety_model.invoke([{"role": "user", "content": safety_prompt}])

        if "UNSAFE" in result.content:
            last_message.content = "I cannot provide that response. Please rephrase your request."

        return None

# 使用安全护栏
from langchain.agents import create_agent

agent = create_agent(
    model="gpt-5.5",
    tools=[search_tool, calculator_tool],
    middleware=[SafetyGuardrailMiddleware()],
)

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

from langchain.agents.middleware import after_agent, AgentState, hook_config
from langgraph.runtime import Runtime
from langchain.messages import AIMessage
from langchain.chat_models import init_chat_model
from typing import Any

safety_model = init_chat_model("gpt-5.4-mini")

@after_agent(can_jump_to=["end"])
def safety_guardrail(state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
    """基于模型的护栏：使用 LLM 评估响应安全性。"""
    # 获取最终的 AI 响应
    if not state["messages"]:
        return None

    last_message = state["messages"][-1]
    if not isinstance(last_message, AIMessage):
        return None

    # 使用模型评估安全性
    safety_prompt = f"""Evaluate if this response is safe and appropriate.
    Respond with only 'SAFE' or 'UNSAFE'.

    Response: {last_message.content}"""

    result = safety_model.invoke([{"role": "user", "content": safety_prompt}])

    if "UNSAFE" in result.content:
        last_message.content = "I cannot provide that response. Please rephrase your request."

    return None

# 使用安全护栏
from langchain.agents import create_agent

agent = create_agent(
    model="gpt-5.5",
    tools=[search_tool, calculator_tool],
    middleware=[safety_guardrail],
)

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

组合多个护栏

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

from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware, HumanInTheLoopMiddleware

agent = create_agent(
    model="gpt-5.5",
    tools=[search_tool, send_email_tool],
    middleware=[
        # 层级 1：确定性输入过滤器（代理前）
        ContentFilterMiddleware(banned_keywords=["hack", "exploit"]),

        # 层级 2：PII 保护（模型前后）
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        PIIMiddleware("email", strategy="redact", apply_to_output=True),

        # 层级 3：敏感工具的人工批准
        HumanInTheLoopMiddleware(interrupt_on={"send_email": True}),

        # 层级 4：基于模型的安全检查（代理后）
        SafetyGuardrailMiddleware(),
    ],
)

其他资源

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

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

护栏

确定性护栏

基于模型的护栏

内置护栏

PII 检测

人机协作

自定义护栏

代理前护栏

代理后护栏

组合多个护栏

其他资源

确定性护栏

基于模型的护栏

​内置护栏

​PII 检测

​人机协作

​自定义护栏

​代理前护栏

​代理后护栏

​组合多个护栏

​其他资源

内置护栏

PII 检测

人机协作

自定义护栏

代理前护栏

代理后护栏

组合多个护栏

其他资源