[!info] related notes

• 所属 MOC: Agent MOC, Agent Evals MOC
• 前置概念: Agent, Orchestration
• 并列概念: Agent 中的人类监督, Agent 中的 Stopping Conditions
• 易混淆概念: Permission Boundary, Human-in-the-loop
• 关系笔记: Agent 测试与评估, Agent 执行闭环

Agent Guardrails

一句话定义

Guardrails 是 Agent 系统里的自动校验层，用来检查输入、输出或工具行为，并由运行时执行拦截等控制。检查可以是确定性规则，也可以调用模型；检测结果并不天然准确，必须与权限和执行边界配合。

核心机制 / 工作原理

Guardrails 挂在四个位置：

1. 输入侧（用户消息进入时）

• Prompt Injection 检测: 检测用户输入是否试图劫持 Agent 行为
• 内容安全: 检测是否包含违法、有害内容
• PII 检测: 检测是否包含个人敏感信息

2. 输出侧（模型回复发出时）

• 内容审核: 检测模型回复是否包含有害内容
• 事实性检查: 检测回复是否基于检索内容（RAG 场景）
• 格式校验: 检测回复是否符合预期格式

3. 工具调用侧（调用工具前后）

• 权限检查: 当前用户/Agent 是否有权调用此工具
• 参数校验: 参数是否合法、是否在允许范围内
• 风险评估: 调用是否需要人类审批
• 速率限制: 防止工具被过度调用

4. 流程控制侧（handoff、状态转换时）

• 步数限制: 防止 Agent 无限循环
• Token 预算: 防止 token 消耗超限
• 时间限制: 防止执行时间过长

OpenAI Agents SDK 的 Guardrails 实现

输入检查可以先阻塞主 Agent，也可以与其并行。两种模式是在延迟与提前执行的成本之间取舍，不能概括为“所有 guardrails 都并行且零延迟”。

模式	执行顺序	成本与边界
阻塞	检查通过后再启动主 Agent	检查耗时进入关键路径；失败时避免启动后续工作
并行	检查与主 Agent 重叠执行	可减少额外等待，但仍消耗资源；检查较慢时仍需等待，失败也不能自动撤销已经发生的外部副作用

下面是 JavaScript SDK 的阻塞输入检查示例，只允许字符串输入，已用 @openai/agents 0.19.0 和模拟模型验证拒绝与放行路径。它演示执行顺序，不承担内容安全检测：

import { Agent } from "@openai/agents";

const agent = new Agent({
  name: "Support",
  inputGuardrails: [{
    name: "String input only",
    runInParallel: false,
    async execute({ input }) {
      return {
        outputInfo: { expected: "string" },
        tripwireTriggered: typeof input !== "string",
      };
    },
  }],
});

该配置交给 SDK 的 run 后，输入检查触发 tripwire 会抛出 InputGuardrailTripwireTriggered。检查不通过时不会先启动主 Agent。Python SDK 使用不同的接口名称，不能把这段配置直接复制过去。

官方文档还区分了作用范围：输入 guardrails 只运行在链条的第一个 Agent，输出 guardrails 只检查产生最终输出的 Agent，工具 guardrails 只作用于其绑定的函数工具。因此，退款、删除等动作的参数、身份、权限和必要审批，应在工具执行前核验；最终输出检查不能代替动作授权。相关运行语义见文末官方来源。

最小例子 / 最小场景

客服 agent 处理退款的 guardrails：

1. 用户输入 → Prompt Injection 检测 → 通过
2. Agent 决定调用 process_refund(amount=5000)
3. → 参数校验: 金额 > 0 ✓
4. → 权限检查: Agent 有退款权限 ✓
5. → 风险评估: 金额 > 1000 → 需要人类审批
6. → 触发 Human-in-the-loop
7. 用户批准
8. → 执行退款
9. → 结果审核: 退款成功 ✓
10. → 回复用户

Guardrails vs 其他安全机制

机制	作用点	特点
Guardrails	运行时自动检查	不依赖人工
Human-in-the-loop	关键节点暂停	依赖人工判断
Permission Boundary	工具执行前的身份、资源与动作授权	可结合静态策略和运行时状态
Content Safety	输入/输出内容	内容层面

详见 Human-in-the-loop, Permission Boundary。

边界与易混淆点

• Guardrails ≠ 敏感词过滤: Guardrails 是多维度的系统级控制，不只是正则匹配。
• 检测与执行不同：提示词或模型分类可参与检测，但是否阻断必须由运行时执行；模型检测本身仍有误报和漏报。
• Guardrails 的位置：共享控制由运行时组织，涉及副作用的校验应贴近具体工具或服务的执行边界。
• Guardrails 的代价：检查消耗计算或 API 资源；端到端延迟取决于串并行安排和检查时长，不能保证零成本，也不能把每个检查耗时简单相加。
• 停止不等于回滚：并行检查失败后终止 run，不代表外部退款或写入已撤销；动作需要事前授权、幂等和明确的恢复策略。

学习检查

1. 为什么并行输入检查能减少等待，却不能保证零延迟、零成本？
2. 如果检查失败前退款工具已经执行，停止 Agent 能否撤销退款？应把授权放在哪里？
3. 输入、输出和工具 guardrails 的作用范围有什么不同？

官方来源

• OpenAI Agents SDK：Guardrails and human review（2026-10-07 核对）：阻塞与并行输入检查、工具审批、校验作用范围。

Related notes

• Agent MOC
• Agentic Systems
• Agent 执行闭环