Gemini Interactions APIの使い方｜状態管理と実行ステップをJavaScriptで扱う

Gemini Interactions APIは、モデルやエージェントの1回の処理を「Interaction」として扱い、出力だけでなく実行ステップ、会話状態、バックグラウンド実行を同じ形式で管理するAPIです。JavaScriptでは @google/genai の interactions.create() を使います。

Googleは2026年6月にInteractions APIを一般提供とし、新規プロジェクト向けに推奨しています。従来の generateContent APIも引き続きサポートされていますが、新しいモデル、ツール、エージェント機能はInteractions APIを中心に展開される方針です。

この記事では、最小リクエスト、steps、previous_interaction_id、保存設定、バックグラウンド実行、generateContentからの移行をJavaScriptで解説します。

情報確認日：2026年7月18日（日本時間）

結論：会話と長時間タスクをIDで管理できる

Interactions APIの中心要素

interactions.create() で1回の処理を作成する
output_text で最終テキストを簡単に取得する
steps で思考、ツール呼び出し、モデル出力を確認する
previous_interaction_id で会話履歴をサーバー側につなぐ
background: true で長時間処理を非同期実行する
保存期間と削除方針を要件に合わせる

Gemini APIのキー作成と最初の呼び出しから確認したい場合は、先にGemini APIをJavaScriptから使う方法を参照してください。

generateContent APIとの違い

項目	generateContent	Interactions API
呼び出し	`models.generateContent()`	`interactions.create()`
主な入力	`contents` と `config`	`input` とトップレベル設定
簡単な出力	`response.text`	`interaction.output_text`
実行履歴	候補とパーツを中心に確認	`steps` で処理の流れを確認
会話状態	チャット履歴をクライアントで管理	`previous_interaction_id`を利用可能
長時間処理	用途ごとの別機能を確認	`background: true`と状態取得

単純なテキスト生成だけなら、どちらでも実装できます。サーバー側の会話状態、実行ステップ、長時間タスク、エージェント利用が必要ならInteractions APIが分かりやすい選択肢です。

JavaScriptで最初のInteractionを作る

SDKをインストールする

mkdir gemini-interactions-sample
cd gemini-interactions-sample
npm init -y
npm pkg set type=module
npm install @google/genai

公式概要では、Interactions APIを利用するJavaScript SDKとして @google/genai 2.3.0以降が案内されています。実装時は最新のSDK要件を確認してください。

export GEMINI_API_KEY="your_api_key_here"
export GEMINI_MODEL="gemini-3.5-flash"

inputを送ってoutput_textを表示する

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});
const model = process.env.GEMINI_MODEL;

if (!model) {
  throw new Error("GEMINI_MODEL is not set");
}

const interaction = await ai.interactions.create({
  model,
  input: "JavaScriptのPromiseを80文字程度で説明してください。",
});

console.log(interaction.output_text);

SDKは GEMINI_API_KEY を環境から読み取ります。モデル名は変わる可能性があるため、本番では環境変数へ分離し、利用可能なモデルを公式一覧で確認します。

Interactionとstepsの構造

Interactionは1回の会話またはタスクを表します。レスポンスにはID、状態、使用量、モデルが生成した実行ステップが含まれます。

console.log({
  id: interaction.id,
  status: interaction.status,
  model: interaction.model,
  usage: interaction.usage,
});

for (const step of interaction.steps) {
  console.log(step.type);
}

interactions.create() の応答にはモデル生成側のステップが返り、保存済みInteractionを取得した場合はユーザー入力を含む履歴も確認できます。画面に最終文章だけを出すなら output_text、デバッグやツール進行を表示するなら steps を使います。

表示の注意：内部的な思考を利用者向けログとしてそのまま扱わず、公開してよいステップ種別と項目を選びます。ツール引数に個人情報や機密情報が含まれる場合もあります。

previous_interaction_idで会話状態をつなぐ

const first = await ai.interactions.create({
  model,
  input: "私の候補日は7月21日と22日です。覚えてください。",
});

const second = await ai.interactions.create({
  model,
  input: "候補日を箇条書きで答えてください。",
  previous_interaction_id: first.id,
});

console.log(second.output_text);

previous_interaction_id を指定すると、サーバーが前のInteractionの会話履歴を取得します。ただし、tools、system_instruction、generation_config は各Interactionにだけ適用されるため、次のターンでも必要なら再指定します。

const next = await ai.interactions.create({
  model,
  input: "候補日の案内メールを作ってください。",
  previous_interaction_id: second.id,
  system_instruction:
    "簡潔で丁寧な日本語のメールを作成してください。",
  tools: configuredTools,
});

アプリ側では利用者・会話ごとに最新Interaction IDを保存します。別の利用者やブラウザタブのIDを混ぜると、会話内容の漏洩につながります。

store設定とデータ保持を理解する

Interactions APIは既定で store: true です。公式概要の2026年7月18日時点の説明では、無料枠は1日、有料枠は55日の保持が案内され、有料プロジェクトでは7・14・28・55日の設定が示されています。条件は変更される可能性があるため、運用時に最新情報を確認してください。

保存を望まない処理では store: false を指定できます。

const stateless = await ai.interactions.create({
  model,
  store: false,
  input: "この公開済み文章を100文字で要約してください。",
});

制約：store: false では、そのInteractionを後続の previous_interaction_id に使えず、バックグラウンド実行とも組み合わせられません。機密性だけでなく、会話・非同期処理の要件と合わせて選びます。

ステートレスで会話を続ける場合は、ユーザー入力とモデルから返された全ステップを正しい順序で次の input に含めます。長い履歴は使用量へ影響するため、コンテキストウィンドウの基本も確認してください。

長時間処理をバックグラウンドで実行する

const job = await ai.interactions.create({
  model,
  input: "提供した資料を章ごとに整理してください。",
  background: true,
});

console.log(job.id);

作成後はIDを保存し、一定間隔で状態を取得します。

const sleep = (ms) =>
  new Promise((resolve) => setTimeout(resolve, ms));

let current = await ai.interactions.get(job.id);

while (current.status === "in_progress") {
  await sleep(5000);
  current = await ai.interactions.get(current.id);
}

if (current.status === "completed") {
  console.log(current.output_text);
} else {
  console.error(`finished: ${current.status}`);
}

公式ガイドでは、主な状態として in_progress、requires_action、completed、failed、cancelled が示されています。requires_action を失敗として捨てず、ツール結果や承認など必要な入力を処理します。

ポーリングの実務上の注意

画面から毎秒大量に問い合わせず、サーバー側で間隔を制御する
全体の待機期限とキャンセル操作を用意する
完了・失敗後はポーリングを止める
結果取得の認可を行い、他人のIDを参照させない
同じ完了通知を複数回処理しても安全にする

generateContentから移行する手順

現在の入力、出力、ストリーム、ツール、エラーをテストで固定する
models.generateContent() を interactions.create() へ変更する
contents を input へ移す
config 内の項目を対応するトップレベル項目へ変更する
response.text を interaction.output_text へ変更する
候補・パーツ依存の処理を steps ベースに見直す
会話をサーバー状態またはステートレスのどちらで持つか決める
保存期間、削除、ログ、料金、レート制限を再確認する

移行対象	確認ポイント
構造化出力	`response_format` の現行形式へ変更
関数呼び出し	`function_call` と `function_result` のstepを処理
ストリーミング	Interactionとstepのイベント種別を処理
会話	Interaction IDの保存、利用者分離、削除
未対応機能	公式概要の制限一覧と現在の要件を比較

すべてのエンドポイントを一度に切り替えず、単発テキスト、会話、ツール、ストリームの順に移すと問題を切り分けやすくなります。旧APIと同じ評価入力で品質、遅延、使用量を比較します。

安全に運用するチェックリスト

APIキーをブラウザへ配信していない
利用者ごとにInteraction IDを分離している
store と保持期間をデータ方針に合わせた
ツールやsystem_instructionをターンごとに再指定している
バックグラウンド処理に期限・キャンセル・認可がある
steps の未知の型をログで検知できる
料金、レート制限、SDKバージョンを監視している

外部ツールを接続する設計では、MCPの基本も関連します。ただし、APIの関数ツールとMCPは同じものではなく、接続方式と責任範囲を分けて考えてください。

よくある質問

generateContent APIはもう使えませんか？

2026年7月18日時点の公式説明では、従来APIも引き続きサポートされています。既存実装を急に止めず、新機能と要件を比較して計画的に移行します。

previous_interaction_idだけでツール設定も引き継がれますか？

引き継がれません。会話履歴は接続されますが、ツール、システム指示、生成設定は各Interactionで再指定します。

store:falseでもバックグラウンド実行できますか？

公式概要では互換性がないと案内されています。バックグラウンド実行は取得可能なInteractionを必要とするため、保存要件を含めて設計してください。

まとめ

Gemini Interactions APIでは、1回の処理をInteractionとして作成し、output_text、steps、ID、状態を使って管理します。会話は previous_interaction_id、長時間処理は background: true で実装できます。

利便性と引き換えに、保存期間、利用者ごとのID分離、ツール設定の再指定が必要です。まず単発リクエストを動かし、状態管理とバックグラウンド実行を要件に応じて追加してください。