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 條評論

登入 後參與評論

還沒有評論,來搶沙發~