Session 15: guardrails — constraints the system can enforce
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. 尽量使用成本低、结果明确的校验
不同检查不需要都调用一个小模型或大模型。通常可以按以下顺序组合:
- 程序规则:类型、范围、格式、白名单、长度、权限和配额。
- 专用检测器:PII、内容安全、提示词注入等有相对明确检测目标的任务。
- 分类模型或 LLM:判断语义、业务意图或复杂上下文。
- 人工审核:对高风险、难以自动判断或后果重大的操作做最终确认。
这样能避免所有请求都增加一次模型调用,也能减少把确定性问题交给概率模型处理的情况。
3. 失败后要有明确策略
校验失败不只有“再问模型一次”这一种处理方式。常见策略包括:
- Reject:直接拒绝执行。
- Fix / Sanitize:对可安全修正的格式或内容做修复。
- Retry / Re-ask:把校验错误反馈给模型,让它重新生成。
- Fallback:降级到更简单、权限更低的路径。
- Human Review:暂停并等待人工确认。
- Log and Continue:对低风险、非阻断性问题记录后继续,但必须有明确依据。
修复和重试都要有限制。例如,JSON 格式错误可以让模型最多重试两次;如果工具参数涉及越权,就不应不断让模型尝试生成另一个参数来绕过规则。
4. 不要把所有规则混成一个万能检查器
“内容是否有害”“输出是否为合法 JSON”“用户是否有权删除这条记录”“网页内容是否可信”,是不同的问题,需要不同的判断依据。
最好让每条规则有明确的输入、输出和失败策略。这样可以单独测试,也方便定位误报、漏报和性能开销。
三、输入校验:主模型调用前做什么?
输入校验通常包括格式、范围、内容和权限四类。
1. 格式与范围校验
这类校验优先使用程序完成。例如,用户传入一个研究主题,可以限制主题长度、必填字段和允许的参数类型。
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 需要把证据整理成统一结构:
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 是否存在可以程序验证;“这份材料是否真的支持这句话”通常需要规则、模型辅助判断或人工复核。两类检查不要混为一谈。
五、工具调用护栏:参数校验与授权要分开
模型发出的工具调用是一个动作请求。它可能结构正确,但仍然没有执行权限。
例如,工具参数为:
{
"table": "customers",
"operation": "delete",
"record_id": 123
}
即使这份 JSON 完全符合 schema,也不能直接执行。程序还需要判断当前用户是否有权限、该工具是否允许删除、目标记录是否属于当前用户,以及该操作是否需要审批。
工具调用前的检查至少应包括:
- 工具是否在当前 Agent 的允许列表中。
- 参数类型、长度、枚举和范围是否正确。
- 当前用户是否有权操作目标资源。
- 操作是否超出当前任务授权范围。
- 是否需要人工确认。
- 下游服务是否也有相应的权限约束。
工具执行后的检查也很重要。例如,工具返回了不可信网页内容、敏感数据或错误信息时,不能不加区分地把结果作为可信指令交给模型。
六、校验失败后,LangGraph 中怎么处理?
LangGraph 可以将校验步骤组织成节点和条件边。下面是一个简化的结构示意:
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 等下游服务继续实施。否则其他调用路径可能绕过图中的节点。
一个简单的输出校验节点
以下示例展示基本思路,不是完整的生产级安全方案:
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 平台。可以先建立一套简单而明确的约束:
- 输入阶段:限制主题长度、参数格式和请求频率;必要时检测明显的恶意请求或业务范围偏离。
- 检索阶段:把网页和文档作为不可信材料,过滤不需要的内容,不执行其中的指令。
- 工具阶段:对工具名称、参数、用户权限、访问范围和调用次数进行程序校验。
- 研究阶段:要求证据结果满足明确的结构约束,区分可程序验证的字段与需要语义判断的证据支持关系。
- 输出阶段:检查格式、敏感信息、引用和业务要求;校验失败时按有限次数重试或拒绝输出。
- 发布阶段:发布、发送邮件、修改线上数据等有外部影响的操作,使用独立授权和人工确认。
- 全流程:限制模型调用、工具调用、重试次数、执行时间和预算,并记录必要的审计信息。
等这些规则逐渐明确后,再考虑使用 Guardrails AI 或 NeMo Guardrails 统一组织校验流程。选择工具的目的应是减少重复实现和提高规则可维护性,而不是把安全责任交给某个框架。
总结
Guardrails 的重点,是把对 Agent 的要求变成可执行、可测试、失败时有明确处理方式的规则。格式和参数约束优先使用程序;需要语义理解的检查可以使用分类模型或 LLM;高风险操作由程序授权,必要时转人工;真正的资源与权限边界还需要下游服务和运行环境保证。
对于 LangGraph 项目,输入校验、输出校验和业务流程控制可以放在图的节点与条件边中,工具调用检查可以通过工具包装器或 Middleware 统一组织,人工审批可以通过中断与持久化实现。但关键权限必须放在实际执行边界,不能因为流程里有一个 Guardrails 节点,就认为整个系统已经安全。