OpenAI Agents SDK 的 Guardrails 与 Tracing 怎么用:安全护栏与链路追踪详解

多智能体上线怕跑偏或出错难查?按 OpenAI Agents SDK 官方文档整理:@input_guardrail 与 @output_guardrail 熔断机制、多代理链路里的护栏生效位置,以及用 trace() 合并追踪与脱敏控制。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

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

Agents SDK 三类护栏触发时机对比

图:本站根据 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 链路追踪:看清每一步交接与耗时

用内置 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 官方文档: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

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同模型

  1. 01

    OpenAI 多模型分工指南:便宜模型做路由、强模型啃难题的官方选型方法

    所有请求都发给最强旗舰模型太慢又费额度?按 OpenAI 官方模型选型指南整理:先用旗舰建质量基线、再逐节点下探最轻档位,让轻量模型承担意图路由与护栏提取、强模型专注复杂多步推理。

    ChatGPTCodex0
  2. 02

    OpenAI Agents SDK 多代理教程:Handoffs 交接与 Agents as Tools 怎么选

    用 OpenAI Agents SDK 搭多智能体系统时,该用 handoffs 交接会话,还是用 agent.as_tool() 把子智能体当工具调?按官方文档讲清两者的控制权差异、上下文过滤、Python 代码写法与选型标准。

    ChatGPT其他 AI 工具0
  3. 03

    GPT-6 发布时间与更新了什么:从 GPT-6 Astra 到聊天版 GPT-6(2026 年 9 月至 10 月时间线)

    GPT-6 什么时候发布?9 月 3 日 Astra 先向有限组织开放,9 月 22 日 Sol 和 Luna 进 Work 和 Codex,10 月 7 日 GPT-6 与 Intelligent UI 进入聊天。按时间线讲更新了什么。

    ChatGPT0
  4. 04

    GPT-6 怎么用:在 ChatGPT 里选到 GPT-6、各套餐能用哪几档,Intelligent UI 能让它做什么(可复制的提问)

    GPT-6 怎么用?在 ChatGPT 模型菜单选 GPT-6,再用 Thinking 滑杆选档,Plus 有 Medium 和 High。讲各套餐能用哪几档,以及 Intelligent UI 的用法和可复制的提问。

    ChatGPT0
  5. 05

    GPT-6 Pro(Astra)怎么用、哪些套餐有:怎么选到 Pro 档、用量限制和 Pro 三档价格

    GPT-6 Pro(Astra)怎么用、哪些套餐有?按 OpenAI 帮助中心核对:聊天里 Pro 档给 Pro 100、Pro 200、Business 和 Enterprise;Plus 在 Work 和 Codex 里含 Astra。讲怎么选到、用量上限和官方 Pro 价格。

    ChatGPT0
  6. 06

    OpenAI Agents SDK 教程:安装、第一个智能体、工具与多智能体交接(Python)

    OpenAI Agents SDK 是什么、怎么上手?按官方 README 和 Quickstart 讲清安装命令、设置 API Key、十行代码跑起第一个智能体、给它加函数工具、用 handoffs 做多智能体分工、在 Trace viewer 里看调用过程,以及它的核心概念各是什么。

    ChatGPT其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  4. 04

    A2A 协议是什么、怎么用:Agent2Agent 智能体互联规范、名片发现与 Python 接入流程

    A2A(Agent2Agent)是由 Google 发起并移交 Linux 基金会托管的开放智能体通信协议,用来让不同团队、不同框架开发的独立智能体跨网络互相派单协作。本文按官方规范讲清 Agent Card、Task 状态机与 Python SDK 接入步骤。

    Gemini其他 AI 工具0
  5. 05

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  6. 06

    CrewAI 多轮对话与记忆怎么配:memory=True 三层记忆、人工介入与 Flows 状态持久化

    刚用上 CrewAI 的人常疑惑 kickoff 跑完就结束,怎么做多轮连续对话与跨次记忆。本文按官方文档拆解 memory=True 的短期/长期/实体三层记忆、嵌入模型配置,以及用 Flows 状态流和 @persist 搭建多轮会话的实战写法。

    其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~