Interactions API 總覽

Interactions API 提供統一的有狀態介面,可使用 Gemini Enterprise Agent Platform 託管的 Gemini 模型和 Agentic Workflows,建構生成式 AI 應用程式和代理工作流程。generateContent API 仍與 Interactions API 一起提供完整支援。

為什麼要使用 Interactions API?

Interactions API 在建構生成式 AI 應用程式和 Agentic Workflows 方面,具備幾項主要優勢:

  • 模型和代理的單一 API:一個統一的端點和模式,可直接呼叫標準 Gemini 模型和專門代理 (例如 Gemini Deep Research 代理和自訂代管代理)。
  • 現成的新功能:包括使用 previous_interaction_id 的選用伺服器端對話狀態、用於偵錯和 UI 轉譯的可觀測執行步驟,以及使用 background=true 的長時間執行工作背景執行。

Interactions API 的運作方式

Interactions API 的核心是 Interaction 資源。Interaction 代表對話或任務中的完整回合,並做為工作階段記錄,包含按時間順序排列的執行 steps 序列:

  • user_input:為該輪對話提供的輸入訊息、多模態檔案或工具結果。使用 interactions.get 擷取的儲存互動包含 user_input 步驟,可提供完整情境,而 interactions.create 回應只會傳回該輪對話中生成的步驟。
  • thought:模型或代理在規劃回覆時,生成的推論過程摘要。
  • 工具呼叫和結果步驟:用戶端或伺服器端工具叫用和輸出內容 (例如 function_call 和 function_result)。
  • model_output:模型或代理產生的最終文字、結構化 JSON 或多模態內容。

呼叫 interactions.create 時,Agent Platform 會處理輸入內容、執行任何已設定的伺服器端工具或代理迴圈,並傳回產生的 Interaction 資源。如需 Python、TypeScript/JavaScript 和 REST 的程式碼範例,請參閱 Interactions API 開發人員指南。

支援的模型

下列 Gemini 模型支援 Interactions API:

按一下即可展開支援的模型

除了上述清單中的 Gemini 模型外,Interactions API 也支援下列生成式音樂模型: * lyria-3-clip-preview 和 lyria-3-pro-preview:生成式音樂模型,用於生成高傳真音訊片段和完整歌曲 (僅支援 store=false 的無狀態互動)。

支援的代理

您可以透過 Interactions API 叫用下列代理,方法是指定 agent 參數,而非 model:

  • antigravity-preview-05-2026:一般用途自主代理,專為多步驟推論、程式設計、檔案作業和工具使用而設計。
  • deep-research-preview-04-2026:Gemini Deep Research 代理,可自主執行多步驟網路研究和合成。
  • 部署在 Agent Platform 的自訂代管代理。

功能和規格

以下各節說明 Interactions API 的核心功能、技術規格和操作注意事項。

狀態管理

根據預設,Interactions API 會將互動內容儲存在伺服器 (store=true) 7 天,以便您使用 previous_interaction_id 串連多輪對話,並執行非同步背景工作 (background=true)。如要選擇無狀態執行,並支援零資料保留 (ZDR) 工作流程,請設定 store=false。詳情請參閱「管理工作階段儲存空間和對話狀態」。

要求和多模態限制

Interactions API 會強制執行下列要求酬載和多模態輸入限制:

  • 要求酬載限制:同步和串流 interactions.create 要求的壓縮 HTTP 要求酬載不得超過 256 MiB。如果 service_tier 設為 deferred (background 和 store 都必須為 true),未壓縮的要求不得超過 9.75 MiB。
  • Cloud Storage 檔案的 URI 限制:標準 Gemini 模型互動要求支援每項要求最多 100 個不同的 Cloud Storage (gs://) URI,包括透過 previous_interaction_id 從先前對話回合沿用的 URI。代管代理互動、Gemini Omni 模型和 Lyria 3 模型不受這項 100 個 URI 的限制。如要瞭解權限和多輪 URI 處理方式,請參閱「存取上傳的 Cloud Storage 檔案」。
  • 多模態項目和詞元限制:標準 Gemini 模型接受的各模態項目數量與 generateContent 相同 (最多 3,000 張圖片和 PDF 檔案、1,000 個音訊檔案、10 部影片,以及最多 6,500 個多模態檔案,包括純文字檔案),受限於模型的 1,048,576 個詞元脈絡窗口。個別 Cloud Storage 檔案不得超過 2 GiB 減 500 KiB,公開 HTTP 或 HTTPS 網址不得超過 15 MiB。如要在單一要求中傳送超過 100 個檔案,請在要求酬載限制內傳遞其他內嵌附件,或呼叫 generateContent。

支援的工具和建立基準

Interactions API 中的 Gemini 3 模型支援下列內建工具、基準建立服務供應商和搜尋功能:

  • 以 Google 搜尋建立基準和以企業適用的網路內容建立基準:使用 Google 搜尋或企業適用的網路內容建立基準,根據即時網路資訊建立模型回覆基準。
  • Gemini Enterprise Agent Platform 的 Agent Search 和 RAG Engine:使用 Agent Search 和 RAG Engine,以私人企業資料儲存庫和文件存放區為基準,生成模型回覆。
  • Exa 網頁搜尋:使用 Exa 搜尋 API 的網頁搜尋結果,建立模型回覆的基準。
  • Parallel Web Search:使用 Parallel Web Systems 搜尋 API 提供的即時公開網路資料,建立模型回覆基準。
  • 網址背景資訊:擷取並分析提示詞中公開網頁網址的內容。
  • 執行程式碼:模型可在安全的沙箱環境中生成及執行 Python 程式碼。
  • 電腦使用:啟用瀏覽器和使用者介面自動化工作流程。
  • 呼叫函式:模型可傳回結構化函式引數,連結至外部工具、API 和資料庫。

Interactions API 支援 Enterprise 網路基準建立和以 Google 搜尋強化事實基礎。使用這些功能時,也必須遵守服務專屬條款。

帳單

Interactions API 的費用是依據詞元用量計算。

中斷或未完成的要求,計費方式如下:

  • 手動取消:如果在互動完成前取消 (例如傳送取消要求),系統會依據取消前耗用的權杖數量收費。
  • 失敗的要求:如果互動要求因內部系統錯誤或後端失敗而失敗,您不需支付失敗要求的費用。

安全性與法規遵循

Interactions API 支援下列安全控管措施、法規遵循認證和端點設定:

  • 端點:Interactions API 支援全域端點 (aiplatform.googleapis.com 上的 locations/global),以及 us 和 eu 多區域端點 (aiplatform.us.rep.googleapis.com 上的 locations/us 和 aiplatform.eu.rep.googleapis.com 上的 locations/eu)。不支援單一區域端點 (例如 us-central1 或 europe-west1)。
  • 資料落地:使用 us 和 eu 多區域端點 (locations/us 和 locations/eu) 時,Interactions API 支援 ML 處理 (使用中) 和儲存的互動資料靜態 (store=true) 資料落地。傳送至 global 端點的要求不提供資料落地保證。
  • 客戶自行管理的加密金鑰 (CMEK):Interactions API 支援儲存互動資料的 CMEK,方法是在 us 和 eu 多區域中,透過服務設定檔 (scope 設為 INTERACTIONS_API) 進行。global 端點不支援 CMEK。
  • VPC Service Controls (VPC-SC):Interactions API 支援 VPC-SC,可協助保護 API 邊界,降低資料竊取風險。
  • 資料存取透明化控管機制 (AXT):Interactions API 支援 AXT 記錄,可在 Google 人員存取儲存的互動內容時,近乎即時地提供資訊。
  • 安全性與法規遵循認證:Interactions API 符合 Google Cloud FedRAMP High 授權範圍內的 FedRAMP High 規定。Interactions API 不符合美國國防部 (DoD) 影響等級 5 (IL5) 或《國際武器貿易條例》(ITAR) 規定。

支援的 SDK

您可以使用統一的 Google Gen AI SDK 或直接發出 REST 呼叫,存取 Interactions API:

  • Python:google-genai 2.3.0 以上版本
  • TypeScript/JavaScript:@google/genai 2.3.0 以上版本
  • Go:google.golang.org/genai
  • Java:com.google.genai:google-genai

舊版 SDK (google-cloud-aiplatform、@google-cloud/vertexai 和 google-generativeai) 不支援 Interactions API。

後續步驟