OpenAI Agents Python 项目中的 Guardrails 机制详解-CSDN博客

本文链接：https://blog.csdn.net/gitblog_01056/article/details/148415051

OpenAI Agents Python 项目中的 Guardrails 机制详解

openai-agents-python A lightweight, powerful framework for multi-agent workflows 项目地址: https://gitcode.com/gh_mirrors/op/openai-agents-python

引言

在现代AI应用开发中，如何确保AI代理(Agent)的安全性和可控性是一个重要课题。OpenAI Agents Python 项目提供的 Guardrails（防护栏）机制，就是一种优雅的解决方案。本文将深入解析这一机制的工作原理和实现方式。

Guardrails 基本概念

Guardrails 是一种与Agent并行运行的检查机制，主要用于对用户输入和Agent输出进行验证。它的核心价值体现在：

成本控制：通过轻量级检查避免不必要的昂贵模型调用
安全防护：防止恶意或不当使用
质量控制：确保输出符合预期标准

Guardrails 类型与工作原理

输入防护栏(Input Guardrails)

输入防护栏在用户输入到达主Agent前进行拦截检查，工作流程如下：

输入接收：获取与主Agent相同的输入内容
检查执行：运行预定义的检查函数
结果判定：根据检查结果决定是否阻断请求

关键特性：

仅对流程中的第一个Agent生效
检查失败会抛出InputGuardrailTripwireTriggered异常

输出防护栏(Output Guardrails)

输出防护栏对Agent的最终输出进行检查，工作流程：

输出捕获：获取Agent生成的最终输出
内容验证：执行预定义的验证逻辑
结果处理：根据验证结果决定是否阻断输出

关键特性：

仅对流程中的最后一个Agent生效
检查失败会抛出OutputGuardrailTripwireTriggered异常

Tripwire 机制解析

Tripwire（触发线）是Guardrails的核心概念，当检测到不符合条件的内容时：

立即触发对应的异常
终止Agent的后续执行
提供详细的触发信息供开发者处理

这种机制确保了问题能够被及时发现和处理，避免资源浪费或不良影响。

实战：实现自定义Guardrail

输入防护栏实现示例

以下是一个检测数学作业请求的防护栏实现：

from pydantic import BaseModel
from agents import (
    Agent,
    GuardrailFunctionOutput,
    InputGuardrailTripwireTriggered,
    RunContextWrapper,
    Runner,
    TResponseInputItem,
    input_guardrail,
)

# 定义防护栏输出结构
class MathHomeworkOutput(BaseModel):
    is_math_homework: bool
    reasoning: str

# 创建防护栏专用Agent
guardrail_agent = Agent(
    name="数学作业检测",
    instructions="判断用户是否在请求帮助完成数学作业",
    output_type=MathHomeworkOutput,
)

# 装饰器标记为输入防护栏
@input_guardrail
async def math_guardrail(
    ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem]
) -> GuardrailFunctionOutput:
    # 调用防护栏Agent进行检查
    result = await Runner.run(guardrail_agent, input, context=ctx.context)
    
    return GuardrailFunctionOutput(
        output_info=result.final_output,  # 包含详细检查信息
        tripwire_triggered=result.final_output.is_math_homework,  # 触发条件
    )

# 主Agent配置防护栏
agent = Agent(
    name="客服助手",
    instructions="你是一个客服助手，负责解答客户问题",
    input_guardrails=[math_guardrail],  # 注册防护栏
)

输出防护栏实现示例

以下是一个检测输出中是否包含数学内容的防护栏：

from pydantic import BaseModel
from agents import (
    Agent,
    GuardrailFunctionOutput,
    OutputGuardrailTripwireTriggered,
    RunContextWrapper,
    Runner,
    output_guardrail,
)

# 定义主Agent输出结构
class MessageOutput(BaseModel):
    response: str

# 定义防护栏输出结构
class MathOutput(BaseModel):
    reasoning: str
    is_math: bool

# 创建输出检查Agent
guardrail_agent = Agent(
    name="数学内容检测",
    instructions="检查输出中是否包含数学内容",
    output_type=MathOutput,
)

# 装饰器标记为输出防护栏
@output_guardrail
async def math_guardrail(
    ctx: RunContextWrapper, agent: Agent, output: MessageOutput
) -> GuardrailFunctionOutput:
    # 调用防护栏Agent检查输出
    result = await Runner.run(guardrail_agent, output.response, context=ctx.context)
    
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_math,
    )

# 主Agent配置输出防护栏
agent = Agent(
    name="客服助手",
    instructions="你是一个客服助手，负责解答客户问题",
    output_guardrails=[math_guardrail],  # 注册输出防护栏
    output_type=MessageOutput,
)