Session 15:Guardrails——给 Agent 加上可执行的约束

Agent Security 讨论的是整个 Agent 系统会遇到哪些安全风险,以及应该如何建立权限边界。Guardrails 更关注这些约束如何落实到程序中:用户输入先检查什么,模型输出如何验证,工具调用参数怎样限制,校验失败后是拒绝、重试还是转人工。

这两个主题有交集,但关注点不完全一样。安全是更大的范围,Guardrails 是实现约束的一组机制。Guardrails 可以用于安全,也可以用于格式、业务范围、数据质量和流程控制。

例如,一个 Research Agent 需要搜索网页、整理证据并生成报告。它可能收到不符合业务范围的请求,检索到包含恶意指令的网页,生成格式错误的结构化数据,或者提出不应该执行的工具调用。Guardrails 要做的,就是在这些环节定义规则,并让程序真正执行这些规则。

一、Guardrails 主要解决哪些问题?

可以按检查发生的阶段来划分。

类型 检查时机 常见场景
Input Guardrails 调用主模型之前 输入格式、业务范围、恶意请求、PII 检测
Retrieval Guardrails 检索完成之后、内容进入模型之前 文档可信度、敏感内容、检索结果过滤
Dialog / Flow Guardrails 多轮对话和流程执行期间 限定业务流程、控制对话状态、限制某些转移
Tool / Execution Guardrails 工具执行之前或之后 参数校验、权限检查、危险操作审批、工具结果校验
Output Guardrails 模型生成结果之后、返回用户之前 格式、内容合规、敏感信息、业务规则、证据引用

NVIDIA NeMo Guardrails 也采用类似的分层方式,将护栏划分为输入、检索、对话、执行和输出等类型,并支持把规则组合成可配置的流程。官方文档:Guardrail Types。

需要注意,分类是为了确定检查位置。一个问题可能需要多层处理。例如,用户要求泄露 API Key,可以在输入阶段识别恶意意图;但真正防止泄露,还需要保证密钥不会无必要地进入模型上下文,并限制工具向外部发送数据。

二、Guardrails 的基本设计原则

1. 规则必须由程序执行

Prompt 可以告诉模型“输出必须是 JSON”“不能访问其他用户的数据”“不要删除数据库”,但这些指令不能保证每次都被遵守。

对于确定性规则,应直接由程序校验。例如,字段类型、字符串长度、允许的枚举值、用户权限、工具调用次数、SQL 操作类型等,都可以用代码判断。

模型适合处理需要语义理解的判断,例如一段话是否偏离业务范围、某个请求是否可能包含提示词注入。但模型的检测结果也可能出错,不能用它替代权限系统。

2. 尽量使用成本低、结果明确的校验

不同检查不需要都调用一个小模型或大模型。通常可以按以下顺序组合:

  1. 程序规则:类型、范围、格式、白名单、长度、权限和配额。
  2. 专用检测器:PII、内容安全、提示词注入等有相对明确检测目标的任务。
  3. 分类模型或 LLM:判断语义、业务意图或复杂上下文。
  4. 人工审核:对高风险、难以自动判断或后果重大的操作做最终确认。

这样能避免所有请求都增加一次模型调用,也能减少把确定性问题交给概率模型处理的情况。

3. 失败后要有明确策略

校验失败不只有“再问模型一次”这一种处理方式。常见策略包括:

  • Reject:直接拒绝执行。
  • Fix / Sanitize:对可安全修正的格式或内容做修复。
  • Retry / Re-ask:把校验错误反馈给模型,让它重新生成。
  • Fallback:降级到更简单、权限更低的路径。
  • Human Review:暂停并等待人工确认。
  • Log and Continue:对低风险、非阻断性问题记录后继续,但必须有明确依据。

修复和重试都要有限制。例如,JSON 格式错误可以让模型最多重试两次;如果工具参数涉及越权,就不应不断让模型尝试生成另一个参数来绕过规则。

4. 不要把所有规则混成一个万能检查器

“内容是否有害”“输出是否为合法 JSON”“用户是否有权删除这条记录”“网页内容是否可信”,是不同的问题,需要不同的判断依据。

最好让每条规则有明确的输入、输出和失败策略。这样可以单独测试,也方便定位误报、漏报和性能开销。

三、输入校验:主模型调用前做什么?

输入校验通常包括格式、范围、内容和权限四类。

1. 格式与范围校验

这类校验优先使用程序完成。例如,用户传入一个研究主题,可以限制主题长度、必填字段和允许的参数类型。

python
def validate_research_request(topic: str) -> str:
    topic = topic.strip()

    if not topic:
        raise ValueError("研究主题不能为空")

    if len(topic) > 300:
        raise ValueError("研究主题不能超过 300 个字符")

    return topic

这类规则不需要 LLM。程序执行更快,行为也更容易预测。

2. 业务范围与内容检测

如果 Agent 只服务于 AI 技术研究,可以检测请求是否明显偏离范围;如果应用有内容安全要求,也可以使用专门的内容检测模型或服务。

但“业务范围检测”和“安全检测”不是同一个任务。比如用户询问烹饪方法,对 AI 研究 Agent 来说可能属于业务范围之外,却不一定是安全风险。系统应根据产品目标决定是拒绝、提示用户换一个主题,还是允许有限回答。

3. 输入检测不能替代工具权限

假设用户输入“把数据库里的所有用户邮箱发给我”。输入检测可能识别出这是一个敏感请求,但如果 Agent 根本没有访问这张表或发送邮件的权限,风险就更容易被控制。

反过来,即使用户输入看起来完全正常,也不代表后续每一个工具调用都安全。因此输入检查只是一层,执行权限还需要单独控制。

四、输出校验:模型生成之后检查什么?

输出校验至少包含三种不同的检查。

1. 结构与类型校验

当模型需要返回 JSON、工具参数或结构化研究结果时,应验证字段是否齐全、类型是否正确、枚举值是否合法。

例如,Research Agent 需要把证据整理成统一结构:

python
from pydantic import BaseModel, Field, HttpUrl

class Evidence(BaseModel):
    title: str = Field(min_length=1, max_length=200)
    url: HttpUrl
    summary: str = Field(min_length=1, max_length=2000)
    supports_claim: bool

这段代码定义了字段约束,之后可以用 Evidence.model_validate(data) 校验字典数据。Pydantic 能检查类型和约束,但它不能证明摘要是真的,也不能证明链接中的材料确实支持某个观点。

如果使用 LangChain 的结构化输出能力,可以让模型按指定 schema 返回结果;不过仍然要处理解析失败、字段校验失败和业务规则不满足的情况。

2. 内容与敏感信息检查

最终回答可以检查是否包含禁止输出的个人信息、密钥格式、业务禁用内容或不允许的 URL。简单规则可以使用正则和专用检测器;需要理解语义的内容可以再用分类模型。

对 API Key 等秘密,最好从源头避免让模型看到,而不是寄希望于输出阶段将其全部过滤掉。输出检查只能减少泄露概率,不能替代密钥管理和权限隔离。

3. 事实与证据校验

Research Agent 的报告需要引用网页或文档。输出校验可以确认每条引用是否存在、URL 是否有效、报告中的 claim 是否有对应证据,以及引用是否覆盖了相关结论。

其中,URL 格式和引用 ID 是否存在可以程序验证;“这份材料是否真的支持这句话”通常需要规则、模型辅助判断或人工复核。两类检查不要混为一谈。

五、工具调用护栏:参数校验与授权要分开

模型发出的工具调用是一个动作请求。它可能结构正确,但仍然没有执行权限。

例如,工具参数为:

json
{
  "table": "customers",
  "operation": "delete",
  "record_id": 123
}

即使这份 JSON 完全符合 schema,也不能直接执行。程序还需要判断当前用户是否有权限、该工具是否允许删除、目标记录是否属于当前用户,以及该操作是否需要审批。

工具调用前的检查至少应包括:

  • 工具是否在当前 Agent 的允许列表中。
  • 参数类型、长度、枚举和范围是否正确。
  • 当前用户是否有权操作目标资源。
  • 操作是否超出当前任务授权范围。
  • 是否需要人工确认。
  • 下游服务是否也有相应的权限约束。

工具执行后的检查也很重要。例如,工具返回了不可信网页内容、敏感数据或错误信息时,不能不加区分地把结果作为可信指令交给模型。

六、校验失败后,LangGraph 中怎么处理?

LangGraph 可以将校验步骤组织成节点和条件边。下面是一个简化的结构示意:

text
START
  |
  v
validate_input
  |
  +-- invalid --> reject_request
  |
  v
research_agent
  |
  v
validate_tool_call
  |
  +-- forbidden --> reject_tool_call
  |
  +-- approval_required --> human_review
  |                            |
  |                            v
  |                       revalidate
  |
  +-- allowed --> execute_tool
                    |
                    v
                validate_result
                    |
                    v
                research_agent
                    |
                    v
                validate_output
                    |
              +-----+------+
              |            |
           valid         invalid
              |            |
              v            v
             END       retry_or_reject

在实现上,可以将输入、输出校验写成独立节点;用条件边选择拒绝、继续或重试;对高风险工具调用使用人工中断机制。若使用 LangChain 的高层 Agent API,还可以结合 Middleware 实现统一的输入/输出检查、PII 处理和工具调用审批。

需要强调,图中出现 validate_tool_call 节点并不能自动保护所有工具。真正的授权检查应该位于工具执行边界,并在数据库、文件系统或外部 API 等下游服务继续实施。否则其他调用路径可能绕过图中的节点。

一个简单的输出校验节点

以下示例展示基本思路,不是完整的生产级安全方案:

python
from typing import TypedDict

class State(TypedDict):
    answer: str
    output_valid: bool
    validation_error: str

def validate_output(state: State) -> dict:
    answer = state["answer"]

    if len(answer) > 12000:
        return {
            "output_valid": False,
            "validation_error": "输出超过长度限制",
        }

    if "sk-" in answer:
        return {
            "output_valid": False,
            "validation_error": "输出疑似包含密钥",
        }

    return {
        "output_valid": True,
        "validation_error": "",
    }

这里的字符串检测只是演示。真实密钥有多种格式,简单匹配 sk- 既会漏检,也可能误判。生产系统应使用合适的秘密扫描器或明确的凭据检测规则,并优先从源头隔离凭据。

在 LangGraph 中,节点返回的状态可以由条件边用于决定下一步,例如通过校验后结束,失败则重试一次或拒绝输出。重试次数也应该写进状态或由程序控制,避免校验与重试之间形成无限循环。

七、第三方 Guardrails 方案怎么选?

1. Guardrails AI

Guardrails AI 是一个 Python 框架,主要用于输入/输出校验和结构化数据生成。它通过 Validators 检查特定风险或输出约束,并支持在失败时采取不同处理方式,例如抛出异常、修复或重新生成。

适合的场景包括:

  • 结构化输出的字段和格式校验。
  • 输入/输出内容规则。
  • 通过可组合的 Validator 增加业务约束。

它不能代替数据库权限、操作系统隔离或工具授权。官方资料:Guardrails AI。

2. NVIDIA NeMo Guardrails

NeMo Guardrails 是一个开源 Python 工具包,支持通过配置和 Colang 流程定义输入、检索、对话、执行和输出护栏。它可以组合安全模型、开源模型、自检 Prompt 或第三方服务。

适合希望将多类护栏统一组织和配置的应用,特别是需要限制对话流程、处理检索内容或检查工具调用的场景。它也提供与 LangChain、LangGraph 等框架集成的文档。

它提供的是可编排的护栏机制,具体规则、检测模型、外部服务和部署方式仍然需要根据项目配置。官方资料:NeMo Guardrails 文档。

3. LangChain Middleware 与 LangGraph

如果项目本身使用 LangChain/LangGraph,可以先检查高层 Agent API 和 Middleware 能否满足需要。例如,PII 检测、工具调用前的人工审批、自定义输入输出校验等能力可以集成到 Agent 执行链路中。

这通常是最直接的起点:先用程序规则和框架提供的机制解决常见问题,再为复杂内容检测接入专门的服务或模型。官方资料:LangChain Guardrails。

4. 不要只按功能列表选型

比较第三方方案时,建议重点检查:

维度 需要确认的问题
检查类型 支持输入、输出、检索、工具调用中的哪些环节?
规则来源 使用代码规则、检测模型、LLM 自检还是外部 API?
失败策略 能拒绝、修复、重试、暂停或转人工吗?
集成方式 能否接入当前的 Python、LangChain 和 LangGraph 流程?
性能与成本 每次请求增加多少延迟和模型调用?
数据处理 内容是否会发往第三方服务?日志如何保存?
可测试性 能否构建测试集,衡量误报、漏报和规则覆盖率?
维护状态 当前版本是否活跃,依赖和 API 是否适合项目长期维护?

八、实际项目中,应该从哪里开始?

以公众号写作 Agent 为例,第一版不需要一上来就引入复杂的 Guardrails 平台。可以先建立一套简单而明确的约束:

  1. 输入阶段:限制主题长度、参数格式和请求频率;必要时检测明显的恶意请求或业务范围偏离。
  2. 检索阶段:把网页和文档作为不可信材料,过滤不需要的内容,不执行其中的指令。
  3. 工具阶段:对工具名称、参数、用户权限、访问范围和调用次数进行程序校验。
  4. 研究阶段:要求证据结果满足明确的结构约束,区分可程序验证的字段与需要语义判断的证据支持关系。
  5. 输出阶段:检查格式、敏感信息、引用和业务要求;校验失败时按有限次数重试或拒绝输出。
  6. 发布阶段:发布、发送邮件、修改线上数据等有外部影响的操作,使用独立授权和人工确认。
  7. 全流程:限制模型调用、工具调用、重试次数、执行时间和预算,并记录必要的审计信息。

等这些规则逐渐明确后,再考虑使用 Guardrails AI 或 NeMo Guardrails 统一组织校验流程。选择工具的目的应是减少重复实现和提高规则可维护性,而不是把安全责任交给某个框架。

总结

Guardrails 的重点,是把对 Agent 的要求变成可执行、可测试、失败时有明确处理方式的规则。格式和参数约束优先使用程序;需要语义理解的检查可以使用分类模型或 LLM;高风险操作由程序授权,必要时转人工;真正的资源与权限边界还需要下游服务和运行环境保证。

对于 LangGraph 项目,输入校验、输出校验和业务流程控制可以放在图的节点与条件边中,工具调用检查可以通过工具包装器或 Middleware 统一组织,人工审批可以通过中断与持久化实现。但关键权限必须放在实际执行边界,不能因为流程里有一个 Guardrails 节点,就认为整个系统已经安全。

本文目录