如何解決運行多代理工作流程時出現的“API逾時錯誤”

在多代理工作流程中，「API 逾時錯誤」很少能透過更改單一數值來解決。規劃器可能會呼叫三個代理，每個代理可能會呼叫 LLM、搜尋服務、資料庫或工具 API，而每一層都可以有自己的逾時時間、重試策略、連線池和並發限制。實際的解決方法是確定哪一層最先逾時，然後在延長等待時間、減少並發呼叫次數、更聰明的重試機制、縮短關鍵路徑或採用非同步作業設計等方案中進行選擇。

權衡取捨至關重要：提高超時時間雖然簡單，但會佔用資源更長時間；頻繁重試會增加負載和成本；降低並發度可以提高穩定性，但會降低峰值吞吐量；並行代理只有在下游服務能夠吸收扇出流量時才能降低實際延遲。對於每個多代理系統，並不存在唯一的最佳設定。

你實際觸發的是哪個暫停？

首先要對故障進行分類，而不是將每次超時視為相同事件。 HTTP 用戶端在連線、讀取、寫入或等待連線池中的連線時都可能發生逾時。例如，HTTPX 文件中列出了四種不同的逾時類型：連線逾時、讀取逾時、寫入逾時和連線池逾時。其預設行為是在網路無活動五秒後觸發逾時，而不是在請求總持續時間達到五秒後觸發。請參閱官方的 HTTPX 逾時文件。

如果您使用 OpenAI Python SDK，其官方 README 檔案指出，請求的預設用戶端逾時時間為 10 分鐘，並且預設逾時失敗會重試兩次。該 SDK 還會自動重試連線錯誤以及 HTTP 408、409、429 和 5xx 回應，並採用較短的指數退避演算法。這些是 SDK 的預設設置，並不保證請求前端的每個代理、負載平衡器、網關或編排器都會等待 10 分鐘。請參閱OpenAI Python SDK 的官方 README 文件。

你應該選擇哪種解決方案？

步驟 1：找出第一個超過截止時間的層

記錄整個工作流程的關聯 ID，以及每個座席和工具呼叫的跨度 ID 或子 ID。記錄開始時間、結束時間、端點、嘗試次數、異常類型、回應狀態（如有），以及取消操作是由呼叫方還是下游服務方發起的。

關鍵問題是「誰先停止等待？」如果 LLM 呼叫在 42 秒內完成，但 API 網關在 30 秒時放棄，那麼將 LLM 用戶端超時時間從 60 秒提高到 120 秒並不會改變任何結果。亞馬遜目前關於 API 閘道 HTTP API 的文件列出了最大整合逾時時間為 30 秒，這很好地說明了為什麼鏈中最短的截止時間通常決定最終結果。請參閱Amazon API 網關 HTTP API 配額。

步驟 2：測量關鍵路徑，而不僅僅是平均延遲

平均延遲可能看起來很健康，但少量慢呼叫才是導致大多數工作流程失敗的原因。至少要追蹤每個依賴項的成功率以及 p50、p95 和 p99 延遲。在扇出階段，也要記錄佇列時間和連線池等待時間，因為「慢 API」實際上可能是客戶端過載，正在等待空閒連線。

使用追蹤來回答三個實際問題：哪個依賴項主導關鍵路徑，多個慢代理是否在可以並發運行時順序運行，以及並發峰值是否與 429、池超時或 5xx 錯誤相吻合。

步驟 3：從外到內建構暫停預算

首先設定端對端工作流程的截止時間，然後縮短內部各層的截止時間，以便底層能夠儘早出現故障，讓編排器有時間恢復。例如，面向使用者的截止時間設為 120 秒，其中 10 秒用於編排和回應處理，剩餘 110 秒用於實際工作。單一工具呼叫可能分配 15 秒，而模型呼叫則可能分配 45 或 60 秒，具體取決於觀察到的尾延遲。

不要盲目複製這些值；它們只是一個預算方法範例，並非通用預設值。請根據您測量的延遲分佈和產品服務等級目標 (SLO) 選擇合適的值。外部截止時間應足夠長，以包含內部呼叫、允許的重試次數、退避延遲和清理時間。

Python 3.11 及更高版本支援asyncio.timeout()為非同步任務設定截止時間。截止時間過後，任務將被取消，上下文管理器會拋出一個異常TimeoutError。請參閱Python 官方 asyncio 超時文件。

import asyncio

async def run_stage():
    try:
        async with asyncio.timeout(90):
            return await run_agents()
    except TimeoutError:
        return {"status": "partial", "reason": "stage_timeout"}

步驟 4：在增加重試次數之前，先限制並發數。

多代理系統經常出現故障，原因在於扇出成長速度超出預期。如果 20 個使用者請求分別啟動 5 個代理，每個代理啟動 2 個工具，那麼在重試之前，系統最多會產生 200 個下游呼叫。如果先進行重試，則可能導致壅塞演變為重試風暴。

當您遇到 429 回應、連線池逾時、佇列時間不斷增加或下游相依性達到飽和等問題時，並發限制器通常是更好的首選方案。 Pythonasyncio.Semaphore提供了一種基於計數器的簡單方法來限制同時進入受保護部分的協程數量。請參閱Python 官方信號量文件。

import asyncio

sem = asyncio.Semaphore(8)

async def guarded_agent_call(agent, task):
    async with sem:
        return await agent.run(task)

這種權衡是經過深思熟慮的：較低的限制可以保護下游服務，但可能會增加應用程式內部的排隊情況。應該根據吞吐量、p95 延遲、速率限制和連接池容量來調整此值，而不是選擇機器可以調度的最大值。

步驟 5：只重試那些以後很可能成功的失敗案例。

對於瞬態連線故障、速率限制、特定伺服器錯誤以及請求逾時等情況，如果重複操作是安全的，重試機制就非常有用。但對於驗證錯誤、驗證失敗、確定性工具錯誤或缺乏冪等性保護的副作用操作，重試機制並非理想的預設選擇。

注意重試次數的倍增。如果 SDK 進行兩次重試，則表示一個邏輯呼叫最多會嘗試三次。如果您的代理層也對整個呼叫進行兩次重試，則理論上該邏輯操作的最大嘗試次數將達到九次：三次外部嘗試乘以三次 SDK 嘗試。如果編排器隨後重試整個包含五個代理程式的階段，則請求量可能會迅速增長。

盡可能集中管理重試權限。對於使用 OpenAI Python SDK 的 LLM 調用，請記住，當前 SDK 預設會對某些類型的故障進行兩次重試。只有在有特定原因且可限制總嘗試次數時，才會新增外部重試。

步驟 6：縮短關鍵路徑，同時避免產生扇出問題

如果規劃、研究、評估和撰寫代理嚴格按照順序運行，則總延遲時間近似等於它們各自運行時間的總和。獨立分支有時可以並行運行，這樣一來，實際運行時間會向最慢的分支靠攏，而不是所有分支運行時間的總和。

Python 的asyncio.TaskGroupTaskGroup 提供了一種結構化的方式來並發運行相關任務。目前的 Python 文件指出，TaskGroup 會等待群組內的任務完成，並在某個任務因非取消異常而失敗時取消剩餘的任務，這比非結構化的任務生成方式提供了更強的安全性。請參閱Python TaskGroup 的官方文件。

並行化並非免費。如果同一服務提供者嚴格限制每分鐘請求數或並發請求數，同時執行四個代理程式可能會將原本緩慢但成功的流程變成快速的 429 回應爆發。因此，僅對真正獨立的工作進行並行化，並保持全局並發限制器有效。

步驟 7：何時應該停止使用同步 HTTP 請求？

如果正常的流程通常會超過網路路徑中最短的請求逾時時間，那麼採用非同步作業模型通常比不斷延長逾時時間更為簡潔。初始 HTTP 請求可以驗證輸入、建立一個持久作業並立即傳回作業 ID。然後，工作進程在請求生命週期之外執行多代理圖，而用戶端則透過輪詢、伺服器發送事件、WebSocket 或 Webhook 接收進度資訊。

當伺服器能夠儘早開始發送有意義的輸出時，串流傳輸非常有用。例如，OpenAI Python SDK 支援對 Responses API 呼叫進行伺服器傳送事件串流。串流傳輸可以提高回應速度，並保持連線持續產生數據，但它並不能自動解決每個代理的最大請求生命週期問題。請參閱OpenAI 官方串流事件參考文件。

當持久性比即時簡便性更重要時，請選擇非同步作業：例如耗時較長的研究任務、需要人工審批的代理工作流程、大量工具呼叫、不希望重複執行的昂貴操作，或必須在客戶端斷開連線後仍能正常運作的工作負載。其代價是需要額外的狀態管理：作業狀態、檢查點、冪等鍵、取消、結果儲存和重試所有權。

步驟 8：在實際負載下驗證修復效果

一次請求成功並不能證明修復方案有效。請在生產環境中預期的並發環境下進行測試，並測量成功率、逾時率、每個邏輯任務的重試次數、p95 和 p99 延遲、佇列延遲、連接池等待時間、下游 429/5xx 錯誤率以及每個已完成工作流程的成本。

如果在 Kubernetes 中運行代理，請將就緒探針和存活探針用於不同的目的。 Kubernetes 將就緒探針定義為確定 Pod 是否應該接收流量的機制，而存活探針則用於決定何時應該重新啟動容器。其文件明確警告，實現不當的存活檢查可能會導致負載下的級聯故障。請參閱Kubernetes 官方探針文件。

對於暫時的過載，進入「未就緒」狀態通常比反覆終止那些健康但繁忙的工作進程更安全。只有在重啟進程才是真正正確的恢復措施的情況下，才應考慮使用存活故障。

如何判斷哪種修復方法最適合您的故障模式？

實際生產基準

對於典型的多代理 API，一個穩健的基線是：為每個工作流程分配一個關聯 ID，跟踪每個代理和工具調用，定義一個端到端截止時間，在其中分配更短的每次調用截止時間，強制執行每個下游提供程序的全局並發限制，保持重試次數有界且冪等，並持久化足夠的狀態以恢復或報告部分完成情況。

然後根據測量結果進行調整。如果系統穩定但速度過慢，則選擇性地並行化獨立任務。如果系統在低負載下速度很快，但在尖峰負載下速度下降，則減少扇出並增加背壓。如果成功的流程自然耗時超過同步請求路徑允許的時間，則切換架構，而不是試圖讓每個代理程式等待更長時間。

官方參考資料

• OpenAI Python SDK：重試與超時
• HTTPX：超時類型和配置
• Python asyncio：超時處理
• Python asyncio：信號量
• Python asyncio：任務群組
• 亞馬遜 API 網關 HTTP API 配額
• Kubernetes：存活探測、就緒偵測與啟動探測
• OpenAI Responses API 串流事件