[!info] related notes

• 所属 MOC: Agent MOC, Agent Evals MOC
• 前置概念: Agent, Orchestration
• 并列概念: Agent 中的人类监督, Agent 中的 Stopping Conditions
• 易混淆概念:
• 关系笔记: 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 实现

OpenAI Agents SDK 中，guardrails 与 Agent 并行执行：

# guardrails 和 agent 同时运行
# guardrails 失败时快速终止，不影响正常路径的延迟
@guardrail
async def check_safety(input):
    if contains_pii(input):
        raise GuardrailTripped(“输入包含 PII”)

关键设计：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 ≠ “让模型注意”: 模型的 system prompt 里写”不要做 XX”不是 guardrail，那是建议。Guardrail 是代码级的硬拦截。
• Guardrails 的位置: 应该在 Agent Runtime 层实现，而不是散落在各处。
• Guardrails 的代价: 每个 guardrail 都增加延迟和成本，需要在安全和性能之间权衡。

Related notes

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