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

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

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

先確認你遷移的是哪一層

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

如果 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，會提取並拼接響應末尾連續的文字塊：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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 或其他工具特定步驟。

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

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 會看不到搜尋、函式呼叫和函式結果。

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

1
2
3
4
5
6

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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 問題常在同一次升級後一起出現。

一份實用排錯順序

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

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

總結

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

官方資料：

• https://ai.google.dev/gemini-api/docs/interactions-breaking-changes-may-2026
• https://ai.google.dev/gemini-api/docs/migrate-to-interactions
• https://ai.google.dev/gemini-api/docs/changelog