# 策展 · X (Twitter) 🔥🔥🔥

> 作者：Google AI Studio (@GoogleAIStudio) · 平台：X (Twitter) · 日期：2026-05-05

> 原始來源：https://x.com/GoogleAIStudio/status/2051334760274755860

## 中文摘要

Gemini API「Interactions API」錯誤訊息大幅優化，讓人類開發者和Agent快速修復問題。

Gemini API推出全新統一的「Interactions API」，專為Agentic程式開發應用設計，重寫錯誤回應機制，提供人類和機器皆能立即理解的詳細脈絡。三項原則主導設計：明確命名問題、列出有效值、精準定位錯誤位置，避免模糊訊息如「invalid request」。

**設計原則**
遵循三項核心規則，讓錯誤訊息具備即時修復能力：
- 明確命名問題：引用錯誤值、指定欄位名稱和路徑。
- 顯示有效選項：列出支援值、預期資料類型。
- 精準描述：如「input[0].name」而非泛泛「invalid input」，或「function_result」而非「bad content」。

**拼字錯誤與未知欄位**
最常見錯誤為參數拼錯或使用不存在欄位，新錯誤訊息直接點名問題欄位，無須猜測。
- 範例curl請求：`{"model": "gemini-3-flash-preview", "completely_unknown_field": "value"}`
- 錯誤回應：`{"message": "Unknown parameter 'completely_unknown_field'."}`，明確指示需移除或修正該欄位。

**缺少必要欄位**
特定內容類型需必填欄位，錯誤訊息指定缺少欄位及內容類型，避免使用者猜測。
- 範例curl請求：`{"model": "gemini-3-flash-preview", "input": [{"type": "function_result", "result": {}}]}`
- 錯誤回應：`{"message": "Missing name in content of type function_result."}`，清楚指出「function_result」類型缺少「name」欄位。

**資料類型不符**
常見於JSON字串模板建置時，將字串「true」傳入需布林true的位置；錯誤訊息說明預期類型及有效格式，甚至處理巢狀欄位。
- 平面範例：`{"model": "gemini-3-flash-preview", "input": "hello", "stream": "invalid"}`
  - 回應：`{"message": "The value is invalid for 'stream'. Expected boolean, expected 'true' or 'false'"}`
- 巢狀範例：`{"model": "gemini-3-flash-preview", "input": [{"type": "function_call", "name": 123}]}`
  - 回應：`{"message": "The value is invalid for 'input[0].name'. Expected string, unexpected character: '1'; expected '\"'"}`，精準指出數字「123」無法作為字串，且缺少引號。

**枚舉值驗證與支援清單**
無效枚舉值會回傳完整有效選項清單，讓Agent無需查閱文件即知可用工具。
- 工具類型範例：`{"model": "gemini-3-flash-preview", "tools": [{"type": "invalid_tool"}]}`
  - 回應：`{"message": "The value 'invalid_tool' is not supported for 'type' at 'tools[0]'. Supported values: 'code_execution', 'google_search', 'mcp_server', 'google_maps', 'retrieval', 'function', 'file_search', 'url_context', 'computer_use'."}`
- 服務等級範例：`{"model": "gemini-3-flash-preview", "service_tier": 123}`
  - 回應：`{"message": "The value for 'service_tier' is invalid. Expected a string. Supported values: 'flex', 'standard', 'priority'."}`

**輸入格式指引**
「input」欄位接受平面內容項目（需「type」）或對話輪次（需「role」），省略任一辨識符即提示所需格式。
- 範例curl請求：`{"model": "gemini-3-flash-preview", "input": [{"text": "Hello"}]}`
- 錯誤回應：`{"message": "Provide a 'type' field (for Content[]), or a 'role' field (for Turn[])" }`，直接指導修正路徑。

**模型或Agent設定衝突**
遺漏模型指定，或同時設定「model」與「agent」，錯誤訊息明確列出所需參數。
- 範例curl請求：`{"input": "Hello"}`
- 錯誤回應：`{"message": "Provide a 'model', or 'agent' parameter."}`

**未來發展**
這些錯誤改善是「Interactions API」邁向正式發布（GA）的關鍵一步，團隊持續優化開發者體驗，適用於人類與Agent。歡迎在Google AI Developer Forum或社群管道提供回饋，分享未解決問題、困惑點或GA前期望功能。

## 標籤

Gemini, 功能更新, Agent, SDK, Google, Gemini