OpenAI Agents SDK #24：两种护栏写法，一个不让 LLM 裸奔的理由

一、input_guardrails.py：用 LLM 做语义判断

结构化输出模型

class MathHomeworkOutput(BaseModel):
    reasoning: str
    is_math_homework: bool

guardrail Agent 的定义

guardrail_agent = Agent(
    name="Guardrail check",
    instructions="Check if the user is asking you to do their math homework.",
    output_type=MathHomeworkOutput,
)

guardrail 函数本体

@input_guardrail
async def math_guardrail(
    context: RunContextWrapper[None],
    agent: Agent,
    input: str | list[TResponseInputItem],
) -> GuardrailFunctionOutput:
    result = await Runner.run(guardrail_agent, input, context=context.context)
    final_output = result.final_output_as(MathHomeworkOutput)
    return GuardrailFunctionOutput(
        output_info=final_output,
        tripwire_triggered=final_output.is_math_homework,
    )

主 Agent 绑定与异常处理

customer_support_agent = Agent(
    name="Customer support agent",
    instructions="...",
    input_guardrails=[math_guardrail],
)

# 对话循环
try:
    result = await Runner.run(customer_support_agent, input=input_data)
    input_data = result.to_input_list()
except InputGuardrailTripwireTriggered:
    input_data.append({"role": "assistant", "content": "Sorry, I can't help you with your math homework."})

二、output_guardrails.py：用代码规则做结构化检查

结构化输出模型

class MessageOutput(BaseModel):
    reasoning: str = Field(description="Agent's reasoning")
    response: str = Field(description="Response to the user")
    user_name: str | None = Field(description="User's name if provided")

guardrail 函数本体

@output_guardrail
async def sensitive_data_check(
    context: RunContextWrapper,
    agent: Agent,
    output: MessageOutput,
) -> GuardrailFunctionOutput:
    phone_number_in_response = "650" in output.response
    phone_number_in_reasoning = "650" in output.reasoning
    return GuardrailFunctionOutput(
        output_info={
            "phone_number_in_response": phone_number_in_response,
            "phone_number_in_reasoning": phone_number_in_reasoning,
        },
        tripwire_triggered=phone_number_in_response or phone_number_in_reasoning,
    )

主 Agent 绑定与异常处理

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    output_type=MessageOutput,
    output_guardrails=[sensitive_data_check],
)

try:
    result = await Runner.run(agent, "What's the capital of California?")
    print("First message passed")
except OutputGuardrailTripwireTriggered as e:
    print(f"Guardrail tripped. Info: {e.guardrail_result.output.output_info}")

三、两种写法的 6 维对比

四、和 #8 的关系：API 层 vs 实现层

• Tool Guardrails：@tool_input_guardrail / @tool_output_guardrail 装饰器，支持对具体 function tool 的调用做前置检查和后置验证，适合需要在工具粒度设拦截的场景
• run_in_parallel 参数：input guardrail 默认 run_in_parallel=True，与主 Agent 并行跑；设为 False 则先跑完 guardrail 再启动主 Agent，延迟换 token 节省
• Workflow Boundaries：input guardrail 只在第一个 agent 入口触发，output guardrail 只在最终 agent 出口触发——中间的 handoff 链不重复执行

五、版本确认：v0.17.1 的三项 guardrail 运行时修复

• fix: streaming guardrail exception cleanup（#3281）
• fix: normalize RunState guardrail payloads（#3289）
• fix: await cancelled output guardrail tasks on tripwire（#3187）

六、实践建议

① 先问「语义还是结构化」

• 「用户是否在问 X 类问题」「输入是否包含敏感意图」——语义判断，走 Agent-based，用 guardrail_agent + 结构化输出模型
• 「输出是否包含电话号码」「返回的 JSON 是否符合格式」「字段长度是否超限」——结构化检查，走 Rule-based，写 Python 规则函数

② 注意 run_in_parallel 的权衡

@input_guardrail(run_in_parallel=False)
async def math_guardrail(...):
    ...

③ 异常捕获后要保证对话连续性

当前版本：本文基于 OpenAI Agents SDK v0.17.2。

下期预告 #25：agent_patterns/ 系列的最后一个模式——Research Bot，一个真正意义上能在互联网上检索信息、自主规划搜索路径的 Agent。看完 #20—#24 的五种编排模式后，Research Bot 是一次综合运用。