Guardrails 与安全护栏

AI-06: Guardrails 与安全护栏

学习目标

• 掌握三级 Guardrails 架构（输入/输出/工具级）
• 理解 Tripwire 触发与三种行为模式
• 理解并行 guardrails 执行与模型取消机制
• 掌握 Run Error Handlers 回退策略

前置知识

本章涉及 Guardrails 的通用原理，建议先阅读：

• Guardrails 护栏系统设计

下文假设你已理解上述概念，直接聚焦 OpenAI Agents SDK 的具体实现。

项目实践

三级 Guardrails 架构

SDK 在三个层级提供护栏能力：

InputGuardrail 运行模式

from agents import InputGuardrail, input_guardrail, Agent
from agents.guardrail import GuardrailFunctionOutput

@input_guardrail
async def safety_check(context, agent, input):
    # 返回 GuardrailFunctionOutput
    return GuardrailFunctionOutput(
        output_info={"checked": True},
        tripwire_triggered=False,  # True = 中断执行
    )

agent = Agent(
    name="SafeAgent",
    input_guardrails=[safety_check],
)

并行 vs 顺序：

• run_in_parallel=True（默认）：guardrails 与模型调用通过 asyncio.gather 并发，tripwire 触发时取消模型任务
• run_in_parallel=False：guardrails 在模型调用之前同步执行，模型不会被调用

ToolGuardrails：工具级细粒度控制

工具级 guardrails 挂载在单个 FunctionTool 上，每个工具可独立配置：

from agents import function_tool, tool_input_guardrail, tool_output_guardrail
from agents.tool_guardrails import ToolInputGuardrailData, ToolGuardrailFunctionOutput

@function_tool(
    tool_input_guardrails=[my_input_guardrail],
    tool_output_guardrails=[my_output_guardrail],
)
def sensitive_tool(query: str) -> str:
    ...

三种行为模式（详细原理见 Guardrails 护栏系统设计）：

行为	说明
AllowBehavior	正常执行
RejectContentBehavior	替换输出为自定义消息
RaiseExceptionBehavior	抛出 TripwireTriggered 异常

Run Error Handlers

Guardrails tripwire 和模型拒绝之外的运行时错误，SDK 提供 RunErrorHandlers 处理：

from agents import Runner, RunConfig

def my_max_turns_handler(input_data):
    # input_data.error: MaxTurnsExceeded 异常
    # input_data.run_data.last_agent: 最后的 Agent
    return {"final_output": "已达到最大轮数限制。"}

result = await Runner.run(
    agent, "输入",
    error_handlers={"max_turns": my_max_turns_handler},
)

两类错误：

• max_turns：超过配置的 turn 上限
• model_refusal：模型安全拒绝（如 OpenAI 安全过滤）

问题与规避

问题	规避方案
并行 guardrails tripwire 触发时 token 已消耗	对成本敏感场景使用 run_in_parallel=False
Guardrail 异常传播未被捕获	使用 error_handlers 配置回退策略
工具级 guardrails 配置遗漏	在 FunctionTool 工厂中默认注册

设计取舍

为什么工具级 guardrails 与 Agent 级分离

工具级 guardrails 允许每个工具独立控制其安全策略（如：一个工具验证路径访问，另一个验证输出格式）。Agent 级 guardrails 适用于全局策略。这种分离使得安全策略可以精确匹配工具的安全需求，而非一刀切。

为什么 tripwire 异常不自动捕获

Tripwire 设计为”快速失败”——异常传播到 Runner.run() 调用方，由调用方决定是返回错误、重试还是记录日志。自动捕获会隐藏安全问题，违反 fail-fast 原则。

参考来源

• OpenAI Agents SDK: Guardrails
• OpenAI Guardrails 指南