Function Calling Migration：從舊 API 到新 SDK 的實戰指南

遷移的真正起點：不只是改個端點

當你看到一個模型版本升級公告，上面寫著“XX API 已棄用，請遷移至新 SDK”時，第一反應是替換請求 URL 和參數名。但對於 Function Calling 而言，這種想法恰恰是遷移失敗的最大源頭。

Function Calling Migration 的核心不是 API 位址更換，而是工具調用機制的範式轉換。在 OpenAI 的 Chat Completions 舊 API 中，函數以 functions 參數定義，模型返回 function_call 物件; 而在新的 Responses API 或 Assistants API 中，工具定義、調用上下文和狀態管理被統一為 tools 參數，並引入了 tool_choice、並行函數調用、以及更嚴格的輸出格式約束。

一個真實案例：某開發團隊將舊 API 中的 20 個函數定義直接複製到新 API，發現模型頻繁返回“無效工具調用”錯誤。排查后發現，新 API 要求每個工具的 description 字段必須顯式說明參數依賴關係（例如“調用此函數前請確保已獲取使用者 ID”），舊 API 並未強制這一點。

最容易失敗的地方：隱式上下文丟失

遷移中最隱蔽的坑是上下文狀態丟失。在舊 API 中，開發者習慣於將函數調用的中間結果拼接回 messages 陣列，模型能自然感知歷史。但在新 API 的 Agent 迴圈中（例如使用 run + tool_outputs 模式），工具執行結果必須嚴格按照 thread 或 step 結構回傳。一旦格式出錯，模型會忽略之前的所有工具輸出，導致Agent工作流中斷。

具體錯誤場景：

你在一個多步驟工具鏈中，先調用了 search_database 傳回 10 條記錄，接著調用 format_results 要求基於前一步結果生成表格。但在新 API 中，如果你將 search_database 的輸出以非標準方式插入 tool_outputs，模型會認為該步驟失敗，直接跳過 format_results。
解決方案：嚴格遵循 SDK 的 submit_tool_outputs 介面，確保每個輸出都附帶對應的 tool_call_id，且輸出內容不超過模型上下文限制（通常為 4096 token）。

筆記型電腦上顯示 Function Calling 遷移檢查清單，列出工具定義審計步驟

第一步：工具定義 audit 與重構

如果你現在就要落地遷移，第一步不是改代碼，而是做工具定義審計：

列出現有所有函數：包括名稱、參數、返回格式。注意標記那些依賴前置工具輸出的函數（例如“生成圖表”依賴“查詢數據”的結果）。
按粒度拆分：新 API 建議每個工具只做一件事。舊 API 中常見的“全能函數”（例如 execute_anything）必須拆成單一職責函數，否則模型容易混淆。
重寫 description：每個工具的 description 必須包含前置條件、輸出格式、以及典型調用場景。例如：
- 舊："获取天气数据"
- 新："根据城市名获取当前天气。需要先调用 check_city_exists 确认城市有效。返回 JSON 格式：{temperature, humidity, condition}"
添加錯誤處理工具：定義一個 report_error 工具，專門接收模型無法處理的異常情況，避免迴圈調用。

完成審計后，在開發環境新建一個 Agent 測試腳本，使用新 API 的 client.responses.create 或 client.beta.threads.runs.create 逐個驗證工具調用。

辦公桌上有新舊 API 對比筆記和一台顯示器，顯示程式碼示例

實操路徑：一個簡單遷移案例

假設你有一個舊 API 代碼：

response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "北京天气如何？"}],
    functions=[{
        "name": "get_weather",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}
    }]
)

迁移至新 API（OpenAI Python SDK v1.x+）：

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    input=[{"role": "user", "content": "北京天气如何？"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
            "description": "根据城市名获取天气。参数 city 必须是中国城市的中文名称。"
        }
    }]
)

注意新 API 使用了 input 而非 messages，且 tools 数组内每个工具需要显式 type 和更详细的 description。

未來方向：從 Function Calling 到 Agent 迴圈

理解遷移背後的邏輯，其實是在為更複雜的 Agent 工作流做準備。當你掌握了工具定義、上下文管理和錯誤恢復后，就可以進入多工具編排、記憶管理與 MCP 協定集成等高級話題。

如果你想從普通開發者轉型成為 Agent 工程師，這篇內容的下一步應該進入更系統的原創付費文章或課程。