Responses API Recovery Workflow：把 Responses API 放進真實 agent 工程恢復路徑

從 Chat Completions 到 Responses API：一個 must-know 的遷移痛點

如果你正把 agent 從 Chat Completions 遷移到 Responses API，很快就會發現：新的介面統一了文字產生、工具呼叫、檔案處理等多個端點，但它的 recovery 邏輯並不 trivial。本文聚焦一個具體矛盾－當 API 呼叫失敗時，怎麼恢復才能不影響整個 agent 連結？

Responses API 在 recovery workflow 中的角色

Responses API 承擔兩個關鍵角色：

• 統一的回應容器：它將模型輸出、工具呼叫結果、檔案參考打包在一個 response 物件裡，你只需要處理這一個對象，而不是拼湊多個端點的輸出。
• 狀態錨點：每個 response 都有唯一的 ID，可用於後續的追溯、重試或 fallback。這意味著你可以把 response ID 當作 recovery 的 checkpoint。

但統一也帶來了耦合風險：一次請求可能同時包含文字和多個工具調用，任一個子任務失敗都會導致整個 response 不符合預期。

失敗模式清單：哪些情況會打破 workflow

實際操作中，以下三種失敗模式最常見：

1. 工具呼叫逾時或異常

當模型決定呼叫一個外部工具（如搜尋資料庫），而工具沒有在規定時間內傳回結果，整個 response 可能被標記為 incomplete。如果你沒有捕捉到這個狀態，agent 會卡住。

2. 回應截斷（truncation）

由於 max_tokens 限制，模型輸出可能被截斷。此時 response 物件裡的 truncated 欄位為 true，但許多人會忽略它，直接使用不完整的輸出做下一步決策。

3. 內容過濾命中

當模型輸出被 OpenAI 的內容安全策略攔截時，response 狀態會是 filtered。這種情況在 agent 產生程式碼或敏感文字時容易發生。

Fallback 介面選擇：什麼時候用 Assistants API 什麼時候降級到 Chat Completions

並不是所有失敗都需要複雜的 recovery。我建議以以下策略分級：

• 逾時 / 截斷 → 直接以相同的輸入重試（最多 3 次），並增加 max_tokens 或縮短工具逾時閾值。
• 工具呼叫失敗 → 如果某個工具持續失敗，應從工具清單中暫時移除它，並用純文字回覆告知使用者“該工具不可用”，避免 agent 死循環。
• 內容過濾 / 連續失敗 → 降級到 Chat Completions API，只用簡單的 system prompt，不做工具調用，確保至少能給用戶一個兜底回复。

程式碼示意（Python）：

def run_with_recovery(messages, tools):
    try:
        response = client.responses.create(
            model="gpt-4o",
            input=messages,
            tools=tools
        )
        if response.status == "incomplete":
            # 检查 truncation
            if response.truncated:
                return retry_with_increased_tokens(messages, tools)
            # 检查工具超时
            if any(call.status == "failed" for call in response.tool_calls):
                return fallback_to_chat(messages)
        return response
    except Exception:
        return fallback_to_chat(messages)

工具调用的恢复陷阱

Responses API 的 tool_calls 数组里每个元素都有 id、type、status。最容易踩的坑是：

• 只检查 status 是否为 "completed"，忽略 "failed" 状态。
• 把失败的工具调用结果拼到 conversation history 里，导致模型后续重复尝试相同工具。

正确做法：对失败的工具调用，添加一条 assistant 消息说明“该工具暂时不可用”，并设置 output_tools 參數參數再次禁止模型。

真實場景：用戶查詢即時股票數據

假設 agent 需要呼叫一個股票價格 API。

• 正常流程：Responses API 呼叫股票工具，返回數據，agent 產生答案。
• 失敗場景：股票 API 逾時（5 秒無回應）。
• 我的 recovery：偵測到工具呼叫狀態失敗 → 從 tools 清單中移除該工具 → 呼叫 Chat Completions 降級，回覆「目前無法取得即時價格，請稍後再試」。

這個流程保證了 agent 不會因為一個下游介面失效而完全崩潰。

何時停止重試、啟動 fallback

不要無限制重試。我設定了：

• 同 input 重試最多 3 次
• 如果 3 次都失敗，進入降級模式
• 降級模式持續 5 分鐘，之後自動恢復原始工具列表

下一步：從普通開發者到 Agent 工程師

以上 recovery 設計只是一個起點。要真正在生產中駕馭 Responses API，你需要理解更多——例如 context 視窗管理、多 agent 協調、權限模型。這些內容在更高階的課程中有系統講解。