结论先说
- 护栏(Guardrails)靠「绊网熔断(Tripwire)」工作:校验函数返回
GuardrailFunctionOutput(tripwire_triggered=True)时,Runner立即中止整条运行并抛出对应异常。 - 认清多代理链路里的生效位置:输入护栏(
input_guardrails)只在整条链第一个智能体接收用户输入时跑;输出护栏(output_guardrails)只在产出最终答复的末尾智能体返回前跑;想卡住中间某次工具调用,要用工具级护栏。 - 小模型前置审查最省钱:在输入护栏里调便宜快速的小模型做意图过滤,一旦触发熔断就省下了主旗舰模型与后续工具链的开销。
- 链路追踪(Tracing)开箱默认启用,自动采集模型生成、函数调用、代理交接和护栏结果,直接在
platform.openai.com/traces可视化回放。 - 多轮对话想并进同一条轨迹,用
with trace("工作流名称"):包裹多次Runner.run;敏感业务可用RunConfig关掉原始输入输出上传或彻底停用追踪。

图:本站根据 OpenAI Agents SDK 官方文档:Guardrails 整理的示意图
本文根据 OpenAI Agents SDK 官方文档《Guardrails》《Tracing》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。安装与基础多代理交接用法请先看 OpenAI Agents SDK 快速入门教程 与 Handoffs 交接与 Agents as Tools 怎么选。
适用于谁
- 想在昂贵的主智能体开始推理前,先用轻量规则或小模型拦住无关提问、提示词注入的开发者;
- 需要检查智能体最终输出有没有泄露内部字段、偏离业务合规要求的团队;
- 多智能体来回交接好几层后结果出错,想知道怎么在控制台把多轮调用串成一条完整调用链(Trace)定位病灶的人。
一、Guardrails 安全护栏:输入拦截与输出把关
在生产系统里,靠在主 Agent 的提示词里写十遍「不许闲聊无关话题」既占上下文又不稳妥。SDK 提供了装饰器式的护栏机制,让你用确定性的 Python 逻辑或独立审查小模型在入口和出口设卡。
输入护栏与异常捕获代码示例
下面这段代码展示了用 @input_guardrail 拦截偏离售后范围的请求,并在外层优雅捕获 InputGuardrailTripwireTriggered 异常:
python
import asyncio
from agents import (
Agent,
GuardrailFunctionOutput,
InputGuardrailTripwireTriggered,
Runner,
input_guardrail,
)
@input_guardrail
async def check_topic_scope(ctx, agent, user_input: str) -> GuardrailFunctionOutput:
# 实战中可在此调用轻量分类模型或正则规则检查输入
off_topic = "帮我写首诗" in str(user_input)
return GuardrailFunctionOutput(
output_info={"reason": "非售后业务请求" if off_topic else "合规"},
tripwire_triggered=off_topic,
)
support_agent = Agent(
name="Order Support",
instructions="你负责解答用户的订单物流与退换货问题。",
input_guardrails=[check_topic_scope],
)
async def main():
try:
result = await Runner.run(support_agent, "帮我写首诗赞美春天")
print(result.final_output)
except InputGuardrailTripwireTriggered as exc:
print("请求已被输入护栏拦截:", exc.guardrail_result.output.output_info)
if __name__ == "__main__":
asyncio.run(main())
同理,使用 @output_guardrail 挂载到 output_guardrails=[...](配合 Pydantic 的 output_type 结构化输出更顺手),可以在最终文本发给前端用户之前检查是否误含内部密钥、手机号或违禁承诺,触发熔断时会抛出 OutputGuardrailTripwireTriggered。
多代理架构的特别提醒:如果你的分诊智能体通过 handoffs 把会话转给了账单专家,挂在分诊智能体上的 output_guardrails 是不会在账单专家结束时触发的——输出护栏必须挂在真正生成最终回复的那个专家智能体上;如果要在子智能体调用高危数据库写工具前后做精细检查,请使用官方提供的工具级护栏(Tool guardrails)。
二、Tracing 链路追踪:看清每一步交接与耗时

图:本站根据 OpenAI Agents SDK 官方文档:Tracing 整理的示意图
多智能体出问题最怕「黑盒猜谜」:到底是分诊转错了人、工具返回了空数组,还是某层护栏误杀了?SDK 默认开启了自动追踪,每次 Runner.run 都会生成一条包含层级切片(Spans)的完整 Trace,登录 https://platform.openai.com/traces 就能按时间轴展开每次大模型输入输出、Token 消耗与耗时。
合并多步运行与控制隐私上报
默认情况下,每调一次 Runner.run 会产生一条独立的 Trace。如果你的业务是「第一轮先规划、第二轮再执行」,想把两次调用绑进同一条轨迹里集中查看,用 trace() 上下文管理器包起来即可(还可用 custom_span() 标记你自己的数据库查询耗时):
python
from agents import Agent, RunConfig, Runner, custom_span, trace
planner = Agent(name="Planner", instructions="给出两步简短排查提纲。")
writer = Agent(name="Writer", instructions="根据提纲写出简明操作答复。")
with trace("售后双阶段处理流"):
step1 = Runner.run_sync(planner, "订单显示已签收但没收到货")
with custom_span("本地订单库核验"):
order_status = "快递柜暂存待取"
step2 = Runner.run_sync(
writer,
f"提纲:{step1.final_output}\n物流状态:{order_status}",
run_config=RunConfig(trace_include_sensitive_data=False),
)
print(step2.final_output)
三、隐私脱敏、关闭追踪与对接第三方观测平台
- 只传结构不传敏感正文:如上例所示,传入
RunConfig(trace_include_sensitive_data=False)(或设对应环境变量)后,追踪记录只保留调用层级、耗时和状态,不会把用户的原始提示词与工具返回值上传到云端面板。 - 彻底关闭内置追踪:在完全内网环境或不想产生任何遥测请求时,调用
set_tracing_disabled(True),或设置环境变量OPENAI_AGENTS_DISABLE_TRACING=1。 - 导出到自建观测后台:SDK 开放了
TracingProcessor扩展接口(add_trace_processor),支持把链路数据同步发送到 Arize Phoenix、Langfuse 等第三方可观测平台(开源追踪工具用法见 Arize Phoenix 大模型追踪教程)。
日常用 Codex 或 ChatGPT 辅助编写调试这类 SDK 代码时,如需补充个人订阅额度,可查看本站 ChatGPT Plus 充值说明。
常见问题
问:输入护栏是等它跑完才开始跑主智能体,还是两边同时跑?
答:SDK 默认让输入护栏与主智能体并发启动以降低首字延迟;如果你的目标是「一旦违规一分钱主模型 Token 都不花」,可以在装饰器上把阻塞模式设为先跑完护栏再启动主模型(以当前版本 @input_guardrail(run_in_parallel=False) 参数为准)。
问:用 LiteLLM 接非 OpenAI 模型跑 Agents SDK 时,控制台 Tracing 还能用吗?
答:只要环境变量里配了有效的 OPENAI_API_KEY 用于上传追踪数据,或者你挂载了第三方开源 TracingProcessor(如 Phoenix),非 OpenAI 模型的调用跨度一样可以被记录下来。
问:护栏自己抛了普通代码异常(比如网络超时),和触发 Tripwire 一样吗?
答:不一样。代码运行报错会直接向上抛出原始 Python 异常;只有显式返回 tripwire_triggered=True 才会抛出专门的 InputGuardrailTripwireTriggered 或 OutputGuardrailTripwireTriggered 业务熔断异常。
相关教程
- OpenAI Agents SDK 快速入门教程(Python)
- OpenAI Agents SDK 多代理:Handoffs 与 Agents as Tools
- Arize Phoenix 大模型追踪与可观测性教程
- OpenAI API 429 错误排查
参考资料
- OpenAI Agents SDK 官方文档:Guardrails — https://openai.github.io/openai-agents-python/guardrails/
- OpenAI Agents SDK 官方文档:Tracing — https://openai.github.io/openai-agents-python/tracing/
- GitHub 仓库:openai/openai-agents-python — https://github.com/openai/openai-agents-python
0 条评论
还没有评论,来抢沙发~