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 でのみステートレスなインタラクションでサポート）。

サポートされているエージェント

model の代わりに agent パラメータを指定することで、Interactions API を介して次のエージェントを呼び出すことができます。

  • 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 では、次のリクエスト ペイロードとマルチモーダル入力の上限が適用されます。

  • リクエスト ペイロードの上限: 圧縮された HTTP リクエスト ペイロードは、 同期 リクエストとストリーミング interactions.create リクエストで 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 と同じモダリティごとのアイテム数（画像と PDF の合計で最大 3,000 個、音声ファイル 1,000 個、動画 10 個、書式なしテキスト ファイルを含むマルチモーダル ファイルの合計で最大 6,500 個）を受け入れます。これは、モデルの 1,048,576 トークンのコンテキスト ウィンドウによって制限されます。個々の Cloud Storage ファイルは 2 GiB から 500 KiB を差し引いたサイズを超えることはできません。また、一般公開の HTTP または HTTPS URL は 15 MiB を超えることはできません。1 つのリクエストで 100 個を超えるファイルを送信するには、リクエスト ペイロードの上限内で追加の添付ファイルをインラインで渡すか、generateContent を呼び出します。

サポートされているツールとグラウンディング

Interactions API の Gemini 3 モデルでは、次の組み込みツール、グラウンディング プロバイダ、検索機能がサポートされています。

  • Google 検索によるグラウンディングとWeb Grounding for Enterprise: Google 検索または Web Grounding for Enterprise のリアルタイム ウェブ情報を使用して、モデルのレスポンスをグラウンディングします。
  • Gemini Enterprise Agent Platform の Agent Search と RAG Engine: Agent Search と RAG Engine を使用して、非公開のエンタープライズ データストアとドキュメント リポジトリに対してモデルの回答をグラウンディングします。
  • Exa ウェブ検索: Exa の検索 API からのウェブ検索結果を使用して、モデルの回答をグラウンディングします。
  • Parallel ウェブ検索: Parallel Web Systems の検索 API が提供するリアルタイムの公開ウェブデータを使用して、モデルの回答をグラウンディングします。
  • URL コンテキスト: プロンプトに含まれる公開ウェブ URL からコンテンツを取得して分析します。
  • コード実行: モデルが安全なサンドボックス環境で Python コードを生成して実行できるようにします。
  • コンピュータの使用: ブラウザとユーザー インターフェースの自動化ワークフローを有効にします。
  • 関数呼び出し: 構造化された関数引数を返すことで、モデルが外部ツール、API、データベースに接続できるようにします。

Interactions API は、エンタープライズ向けウェブ グラウンディングと 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 など）はサポートされていません。
  • データ所在地: Interactions API は、us と eu のマルチリージョン エンドポイント（locations/us と locations/eu）を使用する場合、ML 処理（使用中）と保存されたインタラクション データ（store=true）の両方でデータ所在地をサポートします。global エンドポイントに送信されたリクエストでは、データ所在地は保証されません。
  • 顧客管理の暗号鍵（CMEK）: Interactions API は、us マルチリージョンと eu マルチリージョンのサービス プロファイル（scope が INTERACTIONS_API に設定されている）を介して、保存されたインタラクション データの CMEK をサポートしています。global エンドポイントは CMEK でサポートされていません。
  • VPC Service Controls（VPC-SC）: Interactions API は VPC-SC をサポートしており、API 境界を保護してデータ引き出しのリスクを軽減できます。
  • アクセスの透明性（AXT）: Interactions API は、Google の担当者が保存されたインタラクション コンテンツにアクセスしたときに、準リアルタイムで可視化できるように AXT ログをサポートしています。
  • セキュリティとコンプライアンスの認証: Interactions API は、 Google Cloud FedRAMP High 認証境界内で FedRAMP High 要件を満たしています。Interactions API は、米国国防総省（DoD）のインパクト レベル 5（IL5）または国際武器取引規則（ITAR）の要件に準拠していません。

サポートされている SDK

Interactions API には、統合された Google Gen AI SDK または直接の REST 呼び出しを使用してアクセスできます。

  • 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 をサポートしていません。

次のステップ