Guardrails 会在代理执行的关键点验证和过滤内容,帮助你构建安全、合规的 AI 应用。它们可以检测敏感信息、执行内容策略、验证输出,并在不安全行为造成问题前阻止它们。 常见用例包括:
  • 防止 PII 泄露
  • 检测并阻止 prompt injection 攻击
  • 阻止不当或有害内容
  • 执行业务规则和合规要求
  • 验证输出质量和准确性
你可以使用 middleware 实现 guardrails,在关键点拦截执行:代理开始前、完成后,或模型和工具调用前后。
Middleware 流程图
Guardrails 可以使用两种互补方法实现:

确定性 guardrails

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

基于模型的 guardrails

使用 LLM 或分类器通过语义理解评估内容。可以捕获规则漏掉的细微问题,但速度更慢且成本更高。
LangChain 同时提供内置 guardrails(例如 PII detectionhuman-in-the-loop)和灵活的 middleware 系统,可用任一方法构建自定义 guardrails。

内置 guardrails

PII detection

LangChain 提供内置 middleware,用于检测和处理对话中的 Personally Identifiable Information(PII)。该 middleware 可以检测电子邮件、信用卡、IP 地址等常见 PII 类型。 PII detection middleware 适合有合规要求的医疗和金融应用、需要清理日志的客服代理,以及通常任何处理敏感用户数据的应用。 PII middleware 支持多种策略来处理检测到的 PII:
策略描述示例
redact替换为 [REDACTED_{PII_TYPE}][REDACTED_EMAIL]
mask部分遮盖(例如最后 4 位)****-****-****-1234
hash替换为确定性 hasha8f5f167...
block检测到时抛出异常抛出错误
设置 apply_to_output=True 后,PIIMiddleware 还会通过注册的 stream transformer 对流式 wire 输出进行遮盖,包括文本 deltas、工具调用 args、工具输出和状态快照。需要 langchain>=1.3.2。请参阅 Register transformers on middleware
from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware


agent = create_agent(
    model="gpt-5.4",
    tools=[customer_service_tool, email_tool],
    middleware=[
        # Redact emails in user input before sending to model
        PIIMiddleware(
            "email",
            strategy="redact",
            apply_to_input=True,
        ),
        # Mask credit cards in user input
        PIIMiddleware(
            "credit_card",
            strategy="mask",
            apply_to_input=True,
        ),
        # Block API keys - raise error if detected
        PIIMiddleware(
            "api_key",
            detector=r"sk-[a-zA-Z0-9]{32}",
            strategy="block",
            apply_to_input=True,
        ),
    ],
)

# When user provides PII, it will be handled according to the strategy
result = agent.invoke({
    "messages": [{"role": "user", "content": "My email is john.doe@example.com and card is 5105-1051-0510-5100"}]
})
内置 PII 类型:
  • email:电子邮件地址
  • credit_card:信用卡号(通过 Luhn 验证)
  • ip:IP 地址
  • mac_address:MAC 地址
  • url:URL
配置选项:
参数描述默认值
pii_type要检测的 PII 类型(内置或自定义)必需
strategy如何处理检测到的 PII("block""redact""mask""hash""redact"
detector自定义 detector 函数或正则表达式模式None(使用内置)
apply_to_input在模型调用前检查用户消息True
apply_to_output在模型调用后检查 AI 消息False
apply_to_tool_results在执行后检查工具结果消息False
PII detection 能力的完整详情请参阅 middleware documentation

Human-in-the-loop

LangChain 提供内置 middleware,用于在执行敏感操作前要求人工批准。这是高风险决策中最有效的 guardrails 之一。 Human-in-the-loop middleware 适合金融交易和转账、删除或修改生产数据、向外部方发送通信,以及任何具有重大业务影响的操作。
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.4",
    tools=[search_tool, send_email_tool, delete_database_tool],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                # Require approval for sensitive operations
                "send_email": True,
                "delete_database": True,
                # Auto-approve safe operations
                "search": False,
            }
        ),
    ],
    # Persist the state across interrupts
    checkpointer=InMemorySaver(),
)

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

# Agent will pause and wait for approval before executing sensitive tools
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  # Same thread ID to resume the paused conversation
)
实现审批工作流的完整详情请参阅 human-in-the-loop documentation

自定义 guardrails

如需更复杂的 guardrails,可以创建在代理执行前或执行后运行的自定义 middleware。这让你可以完全控制验证逻辑、内容过滤和安全检查。

代理前 guardrails

使用 “before agent” hooks 在每次调用开始时验证一次请求。这适合会话级检查,例如身份验证、速率限制,或在任何处理开始前阻止不当请求。
from typing import Any

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

class ContentFilterMiddleware(AgentMiddleware):
    """Deterministic guardrail: Block requests containing banned keywords."""

    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:
        # Get the first user message
        if not state["messages"]:
            return None

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

        content = first_message.content.lower()

        # Check for banned keywords
        for keyword in self.banned_keywords:
            if keyword in content:
                # Block execution before any processing
                return {
                    "messages": [{
                        "role": "assistant",
                        "content": "I cannot process requests containing inappropriate content. Please rephrase your request."
                    }],
                    "jump_to": "end"
                }

        return None

# Use the custom guardrail
from langchain.agents import create_agent

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

# This request will be blocked before any processing
result = agent.invoke({
    "messages": [{"role": "user", "content": "How do I hack into a database?"}]
})

代理后 guardrails

使用 “after agent” hooks 在返回给用户之前验证一次最终输出。这适合基于模型的安全检查、质量验证,或对完整代理响应进行最终合规扫描。
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):
    """Model-based guardrail: Use an LLM to evaluate response safety."""

    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:
        # Get the final AI response
        if not state["messages"]:
            return None

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

        # Use a model to evaluate safety
        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

# Use the safety guardrail
from langchain.agents import create_agent

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

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

组合多个 guardrails

可以通过将多个 guardrails 添加到 middleware 数组来堆叠它们。它们会按顺序执行,让你构建分层保护:
from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware, HumanInTheLoopMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, send_email_tool],
    middleware=[
        # Layer 1: Deterministic input filter (before agent)
        ContentFilterMiddleware(banned_keywords=["hack", "exploit"]),

        # Layer 2: PII protection (before and after model)
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        PIIMiddleware("email", strategy="redact", apply_to_output=True),

        # Layer 3: Human approval for sensitive tools
        HumanInTheLoopMiddleware(interrupt_on={"send_email": True}),

        # Layer 4: Model-based safety check (after agent)
        SafetyGuardrailMiddleware(),
    ],
)

其他资源