Interactions API

Interactions API は、Gemini を使用して構築するための新しい標準であり、すべての新しいプロジェクトにおすすめします。エージェント ワークフロー、サーバーサイドの状態管理、複雑なマルチモーダル、マルチターンの会話向けに最適化されています。元の generateContent API は引き続き完全にサポートされます。

Interactions API を使用する理由

  • サーバーサイドの履歴管理: previous_interaction_id を使用して、マルチターンのフローを簡素化します。サーバーはデフォルトで状態を有効にしますが（store=true）、store=false を設定してステートレス動作を選択することもできます。
  • 実行ステップの可視化: 型付きステップにより、複雑なフローのデバッグが容易になり、中間イベント（思考や検索ウィジェットなど）の UI をレンダリングできます。
  • エージェント ワークフロー向けに構築: 型付き実行ステップを通じて、マルチステップ ツールの使用、オーケストレーション、複雑な推論フローをネイティブにサポートします。
  • 長時間実行タスクとバックグラウンド タスク: background=true を使用して、Deep Think や Deep Research などの時間のかかるオペレーションをバックグラウンド プロセスにオフロードできます。
  • 新しいモデルと機能へのアクセス: 今後、コア メインライン ファミリー以外の新しいモデルと、新しいエージェント機能とツールは、Interactions API でのみリリースされます。

新しいプロジェクトを開始する場合、エージェント アプリケーションを構築する場合、またはサーバーサイドの会話管理が必要な場合は、Interactions API を使用します 。ニーズに合った既存の統合がある場合、または Batch API や明示的なキャッシュなど、Interactions API でまだ利用できない機能が必要な場合は、generateContent を使用します。

始める

  • コーディング エージェントを設定する: Gemini Docs MCP に接続し、 最新のデベロッパー ドキュメントとベスト プラクティスにアシスタントが直接アクセスできるように、gemini-interactions-api スキルをインストールします。 コーディング エージェントを設定する →
  • generateContent から移行する: 既存の統合がある場合は、 移行ガイドに沿って Interactions API に移行します。
  • クイックスタートを試す: Interactions API クイックスタートの最小限の動作例から始めます。

機能ガイド

これらのガイドで、Interactions API の特定の機能について説明します。これらのページの切り替えを使用して、generateContent と Interactions API を切り替えることができます。

Interactions API の仕組み

Interactions API は、コアリソースであるInteraction を中心に構成されています。Interaction は、会話またはタスクの完全なターンを表します。セッション レコードとして機能し、インタラクションの履歴全体を実行ステップ の時系列シーケンスとして含みます。これらのステップには、モデルの思考、サーバーサイドまたはクライアントサイドのツール呼び出しと結果（function_call や function_result など）、最終的な model_output が含まれます。保存されたリソース（interactions.get で取得）には、完全なコンテキストの user_input ステップも含まれますが、interactions.create レスポンスはモデル生成ステップのみを返します。

interactions.create を呼び出すと、新しい Interaction リソースが作成されます。

SDK の便利なプロパティを使用して出力にアクセスする

Interactions API は、思考、検索クエリ、関数呼び出しなどの実行ステップの構造化されたタイムラインを返しますが、最終的なモデルのレスポンスを取得するためにステップを手動でトラバースする必要はありません。

Google GenAI SDK は、返された Interaction オブジェクトに便利なプロパティを直接提供し、さまざまなモダリティの出力にアクセスできるようにします。

SDK の便利なプロパティ 戻り値の型 説明
interaction.output_text 文字列 モデルのレスポンスの最後のテキスト ブロックを返します。レスポンスが複数の連続する TextContent ブロックに分割されている場合は、自動的に結合されます。テキスト以外のコンテンツ（思考、画像、音声、ツール呼び出しなど）で区切られた以前のテキスト ブロックは含まれません。複雑なマルチモーダル レスポンスやインターリーブされたマルチモーダル レスポンスの場合は、代わりに steps を手動で反復処理する必要があります。
interaction.output_image ImageContent または None 現在のリクエストでモデルによって生成された最後の画像ブロックを返します。
interaction.output_audio AudioContent または None 現在のリクエストでモデルによって生成された最後の音声ブロックを返します。

中間思考プロセスのレンダリング、ステップごとのツール呼び出しの検査、デバッグなどの高度なユースケースでは、引き続き生の interaction.steps タイムラインを手動で検査してトラバースできます。

サーバーサイドの状態管理

会話を続行するには、 previous_interaction_id パラメータを使用して、完了したインタラクションの id を後続の呼び出しで使用します。サーバーはこの ID を使用して会話履歴を取得するため、チャット履歴全体を再送信する必要はありません。

previous_interaction_id パラメータは、previous_interaction_id を使用して会話履歴（入力と出力）のみを保持します。他のパラメータはインタラクション スコープ であり、現在生成している特定のインタラクションにのみ適用されます。

  • tools
  • system_instruction
  • generation_config（thinking_level、temperature など）

つまり、これらのパラメータを適用する場合は、新しいインタラクションごとに再指定する必要があります。このサーバーサイドの状態管理は省略可能です。リクエストごとに会話履歴全体を送信して、ステートレス モードで動作することもできます。

データの保存と保持

デフォルトでは、API はすべての Interaction オブジェクト（store=true）を保存して、サーバーサイドの状態管理機能（previous_interaction_id を使用）、バックグラウンド実行（background=true を使用）、可観測性の目的での使用を簡素化します。

  • 有料階層: システムはインタラクションを 55 日間 保持します。
  • 無料枠: システムはインタラクションを 1 日間 保持します。

この動作を希望しない場合は、リクエストで store=false を設定します。このコントロールは状態管理とは別のもので、任意のインタラクションの保存をオプトアウトできます。ただし、store=false は background=true と互換性がなく、後続のターンで previous_interaction_id を使用できなくなることに注意してください。

保存されたインタラクションは、 API リファレンスにある delete メソッドを使用していつでも削除できます。インタラクションを削除できるのは、インタラクション ID がわかっている場合のみです。

保持期間が終了すると、データは自動的に削除されます。

システムは、利用規約に従って Interaction オブジェクトを処理します。

ベスト プラクティス

  • キャッシュ ヒット率: previous_interaction_id を使用して会話を続行すると、システムは会話履歴の暗黙的なキャッシュをより簡単に利用できるため、パフォーマンスが向上し、費用が削減されます。
  • インタラクションの組み合わせ: 会話内でエージェントと モデルのインタラクションを柔軟に組み合わせることができます。たとえば、Deep Research エージェントなどの特殊なエージェントを使用して初期データ収集を行い、標準の Gemini モデルを使用して要約や再フォーマットなどのフォローアップ タスクを実行し、これらのステップを previous_interaction_id でリンクできます。

サポートされているモデルとエージェント

モデル名 タイプ モデル ID
Gemini 3.5 Flash モデル gemini-3.5-flash
Gemini 3.1 Flash-Lite モデル gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite プレビュー モデル gemini-3.1-flash-lite-preview
Gemini 3.1 Pro プレビュー モデル gemini-3.1-pro-preview
Gemini 3 Flash プレビュー モデル gemini-3-flash-preview
Gemini 2.5 Pro モデル gemini-2.5-pro
Gemini 2.5 Flash モデル gemini-2.5-flash
Gemini 2.5 Flash-lite モデル gemini-2.5-flash-lite
Lyria 3 Clip プレビュー モデル lyria-3-clip-preview
Lyria 3 Pro プレビュー モデル lyria-3-pro-preview
Deep Research プレビュー エージェント deep-research-pro-preview-12-2025
Deep Research プレビュー エージェント deep-research-preview-04-2026
Deep Research プレビュー エージェント deep-research-max-preview-04-2026

SDK

Interactions API にアクセスするには、最新バージョンの Google GenAI SDK を使用します。

  • Python の場合、これは 1.55.0 バージョン以降の google-genai パッケージです。
  • JavaScript の場合、これは 1.33.0 バージョン以降の @google/genai パッケージです。

SDK のインストール方法について詳しくは、 ライブラリのページをご覧ください。

制限事項

  • ベータ版ステータス: Interactions API はベータ版/プレビュー版です。機能とスキーマは変更される可能性があります。
  • リモート MCP: Gemini 3 はリモート MCP をサポートしていません。近日中にサポートされる予定です。

次の機能は generateContent API でサポートされていますが、Interactions API ではまだ利用できません 。

破壊的変更

Interactions API は現在、初期ベータ版の段階です。実際の使用状況とデベロッパーからのフィードバックに基づいて、API 機能、リソース スキーマ、SDK インターフェースの開発と改良を積極的に行っています。そのため、破壊的変更が発生する可能性があります 。

既存の破壊的変更:

  • ステップ スキーマ: 新しい steps 配列が outputs 配列に置き換えられ、各インタラクション ターンの構造化されたタイムラインが提供されます。

最新の破壊的変更と移行方法については、破壊的変更の移行ガイド（2026 年 5 月）をご覧ください。

その他の更新には、入力と出力のスキーマ、SDK メソッドのシグネチャとオブジェクト構造、特定の機能の動作の変更が含まれる可能性があります。

本番環境のワークロードでは、引き続き標準の generateContent API を使用する必要があります。安定したデプロイには引き続きこの方法をおすすめします。Google はこの API の開発とメンテナンスを積極的に行っていきます。

フィードバック

皆様からのフィードバックは、Interactions API の開発に不可欠です。 Google AI デベロッパー コミュニティ フォーラムで、ご意見やバグの報告、機能のリクエストをお寄せください。

次のステップ