Gemini Interactions API 遷移指南：outputs 改為 steps 後怎麼排錯

Sun, 12 Jul 2026 10:33:00 +0800

Gemini Interactions API 已成為新專案推薦的統一介面。它把一次生成、工具呼叫、思考過程、工具結果和最終回覆都表示為可觀察的執行步驟，適合 Agent、長任務和需要顯示中間狀態的應用。

這也意味著舊程式碼不能再假定響應中有 outputs。從 2026 年 5 月起，新 schema 開始成為預設；舊 schema 已在 6 月 8 日移除。若遷移後出現空回覆、工具呼叫丟失、SSE 事件不觸發或歷史上下文斷裂，通常不是模型問題，而是仍按舊結構讀取資料。

先確認你遷移的是哪一層

排錯前先把問題歸類，避免只改一個欄位：

層級	舊做法	新做法
最終文字	遍歷 `outputs` 找文字	簡單場景讀 `interaction.output_text`
完整響應	在 `outputs` 中找內容、工具或搜尋結果	遍歷 `interaction.steps`，按 `type` 處理
工具呼叫	從舊 content 型別中解析	處理 `function_call`、`function_result` 等步驟
流式事件	`content.start`、`content.delta`、`content.stop`	`step.start`、`step.delta`、`step.stop`
多輪歷史	回傳舊 `outputs`	伺服器端用 `previous_interaction_id`，或客戶端回傳 `steps`

如果 SDK 仍是 Python 1.x 或 JavaScript 1.x，先確認版本。官方遷移說明要求使用 Python ≥2.0.0 或 JavaScript ≥2.0.0 來自動採用新 schema；但升級 SDK 不會自動修復你自己寫的 outputs 解析器、SSE 處理器和前端狀態機。

最簡單的修復：用 `output_text` 讀取最終文字

只處理純文字問答時，不必手動從 steps 中找最後一段文字。新版 SDK 提供 output_text，會提取並拼接響應末尾連續的文字塊：

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="用三句話解釋什麼是 prompt caching。",
)

print(interaction.output_text)

如果你遷移後把 interaction.outputs[-1].text 原樣保留，常見結果是屬性不存在、索引失敗，或錯誤地把物件序列化成空字串。先替換成 interaction.output_text，再補充複雜場景的步驟解析。

output_text 不適合所有響應：當文字被 thought、圖片、音訊或工具呼叫隔開時，它不會替你還原所有交錯內容。需要展示完整執行過程時，應遍歷 steps。

如何正確遍歷 `steps`

新 schema 將過程表示為有型別的步驟。至少要識別 user_input、model_output、function_call 和 function_result；如果使用服務端工具，還會看到 google_search_call、google_search_result 或其他工具特定步驟。

下面示例只收集最終模型輸出中的文字：

def collect_model_text(interaction):
    chunks = []

    for step in interaction.steps:
        if step.type != "model_output":
            continue

        for item in step.content or []:
            if item.type == "text":
                chunks.append(item.text)

    return "".join(chunks)


print(collect_model_text(interaction))

真實專案中不要假設每個步驟都有 content，也不要把 thought 當成最終答案。先根據 step.type 分支，再讀取該型別允許的欄位。把未知步驟記錄為型別、ID 和狀態，保留向前相容空間；不要因為出現新的工具步驟就讓整個請求失敗。

工具呼叫為什麼“消失”了

舊 schema 常把服務端工具操作包在 outputs 的特定內容型別裡。新 schema 將它們拆為獨立步驟，因此只掃描 model_output 會看不到搜尋、函式呼叫和函式結果。

例如，函式呼叫應這樣讀取：

for (const step of interaction.steps) {
  if (step.type === 'function_call') {
    console.log(`Calling ${step.name}`);
    console.log(step.arguments);
  }
}

服務端 Google Search 也應分別處理呼叫和結果步驟，而不是從最終文字中猜測有沒有執行搜尋。對於客戶端函式工具，收到 requires_action 後，提交對應 function_result，並繼續使用該 interaction 的狀態完成後續流程。

流式 SSE 事件要一起遷移

只改 REST 響應解析、不改流式處理器，前端通常會表現為“請求成功但頁面不更新”。新版事件名稱如下：

舊事件	新事件
`interaction.start`	`interaction.created`
`interaction.complete`	`interaction.completed`
`content.start`	`step.start`
`content.delta`	`step.delta`
`content.stop`	`step.stop`
`interaction.status_update`	`interaction.in_progress`、`interaction.requires_action` 等狀態事件

函式呼叫的引數也不再保證一次性完整到達。流中 step.start 會先給出函式名，後續多個 step.delta 事件以部分 JSON 引數逐段傳遞。客戶端必須累積引數，在 step.stop 或需要動作的狀態後再解析完整 JSON；不要對每一個 delta 都直接 JSON.parse()。

let rawArguments = '';

for await (const event of stream) {
  if (event.event_type === 'step.delta' && event.delta?.type === 'arguments') {
    rawArguments += event.delta.partial_arguments;
  }

  if (event.event_type === 'step.stop') {
    // 只在對應 function_call 步驟完成後解析 rawArguments。
  }
}

多輪對話別再回傳 `outputs`

舊的無狀態實現常把上一輪的 outputs 收集後塞回下一輪 input。遷移後有兩種更清晰的選擇：

使用預設伺服器端狀態，透過 previous_interaction_id 延續同一會話；
必須自行管理歷史時，回傳上一輪的 steps，再追加新的 user_input 步驟。

伺服器端狀態更適合普通多輪對話；需要嚴格控制儲存內容、跨系統遷移或離線回放時，再使用客戶端狀態。無論選擇哪種，都不要同時拼接舊 outputs 和新 steps，否則容易產生重複上下文、工具結果不匹配或 token 激增。

`response_format` 也可能是報錯來源

這次遷移不只改了輸出陣列。結構化輸出和多模態配置也統一到頂層 response_format：

原先的 response_mime_type 已移除；在 response_format 條目中指定 mime_type。
JSON schema 需要放入帶有 type: "text" 的格式物件。
圖片配置從 generation_config 移到 response_format 中的 type: "image" 條目。
多模態輸出需要使用格式條目陣列。

如果介面返回 400，除了檢查 steps，也搜尋程式碼中的 response_mime_type、generation_config.image_config 和舊版單物件 response_format。這些舊欄位與 outputs 問題常在同一次升級後一起出現。

一份實用排錯順序

升級 Google GenAI SDK，並記錄實際版本。
用一個無工具、非流式的最小請求驗證 interaction.output_text。
列印 interaction.steps 的型別和狀態，確認程式收到的是新 schema。
分別遷移函式呼叫、服務端搜尋和工具結果的解析邏輯。
修改 SSE 事件訂閱和引數累積邏輯。
檢查多輪歷史是否改為 previous_interaction_id 或 steps。
搜尋並替換舊的 response_format 相關欄位。
用文字、工具呼叫、流式輸出和失敗重試各跑一次迴歸測試。

不要為了臨時恢復舊程式碼去依賴過去的 Api-Revision 頭。舊 schema 的過渡期已經結束；現在應把遷移作為正式相容性修復，而不是繼續保留兩套不一致的解析器。

總結

outputs 改為 steps 的本質是：Interactions API 不再把所有過程塞進一個輸出列表，而是顯式暴露輸入、思考、工具、結果和最終輸出。純文字場景優先使用 interaction.output_text；Agent、工具、流式和多模態場景按 step.type 建立明確分支；多輪會話改用 previous_interaction_id 或 steps。按這三個原則遷移，絕大多數“無輸出”“工具丟失”和“SSE 不重新整理”問題都能定位。

官方資料：

API遷移 on KnightLi的博客

Gemini Interactions API 遷移指南：outputs 改為 steps 後怎麼排錯

先確認你遷移的是哪一層

最簡單的修復：用 output_text 讀取最終文字

如何正確遍歷 steps