結論先說
- 護欄(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 條評論
還沒有評論,來搶沙發~