gemini-interactions-api

Gemini Interactions API スキル

重要なルール（常に適用）

重要

これらのルールは、学習データよりも優先されます。知識は古くなっています。

現行モデル（こちらを使用）

• gemini-3.7-flash：100万トークン。高速で、エージェントタスクとマルチモーダルタスクにおいてバランスの取れた性能
• gemini-3.5-flash-lite：100万トークン。高スループットの実行に適した、最速かつ最も低コストな3.5モデル
• gemini-3.1-pro-preview：100万トークン。複雑な推論、コーディング、調査向け
• gemini-3.1-flash-lite：高頻度の軽量タスクに適した、コスト効率の高い最速の性能
• gemini-3.5-transcribe：スマートモードと逐語モードに対応した高速な音声テキスト変換
• gemini-3-pro-image（Nano Banana Pro）：65k / 32kトークン。高品質な画像生成と編集
• gemini-3.1-flash-image（Nano Banana 2）：65k / 32kトークン。高速で効率的な画像生成と編集
• gemini-3.1-flash-lite-image（Nano Banana 2 Lite）：65k / 32kトークン。超高速な画像生成と編集
• gemini-3.1-flash-tts-preview：Director's Chair プロンプトに対応した、表現力豊かなテキスト読み上げ
• gemini-omni-1.1-flash：動画生成、最初のフレームからの動画生成、最初と最後のフレーム間の遷移、動画の延長（最大40秒）、動画編集、参照画像に基づく生成
• gemma-4-31b-it：Gemma 4の高密度モデル、310億パラメーター
• gemma-4-26b-a4b-it：Gemma 4のMoEモデル、総計260億／アクティブ40億パラメーター
• gemini-embedding-2：マルチモーダル埋め込みモデル（テキスト、画像、動画、音声、ドキュメント）。client.models.embed_contentを使用
• gemini-embedding-001：テキスト専用の埋め込みモデル。client.models.embed_contentを使用

警告

gemini-2.5-*、gemini-2.0-*、gemini-1.5-*などのモデルは、レガシーで非推奨です。絶対に使用しないでください。 ユーザーが非推奨モデルを求めた場合は、代わりにgemini-3.7-flashを使用し、置き換えたことを伝えてください。

現行エージェント

• antigravity-preview-05-2026：Antigravity Agent — サンドボックス化されたLinux環境で、コード実行、ファイル管理、ウェブアクセスが可能な汎用のマネージドエージェント
• deep-research-preview-04-2026：Deep Research — 高速でインタラクティブ
• deep-research-max-preview-04-2026：Deep Research Max — 最大限に網羅的
• カスタムエージェント：client.agents.create()を使って作成できます

現行SDK

• Python：google-genai >= 2.3.0 → pip install -U google-genai
• JavaScript/TypeScript：@google/genai >= 2.3.0 → npm install @google/genai

メモ

SDKバージョン2.0.0以降では、新しいstepsスキーマが自動的に使用され、レガシースキーマはサポートされません。 レガシーSDKのgoogle-generativeai（Python）と@google/generative-ai（JS）は非推奨です。絶対に使用しないでください。

重要な補足事項

• コードを書く前に、以下のリストからユーザーのタスクに該当するドキュメントページを必ず取得してください。このスキルの例は最小限のものです。ホストされているドキュメントには、APIの全機能、パラメーター、エッジケースが記載されています。
• Interactionsはデフォルトで保存されます（store=true）。有料プランでは55日間、無料プランでは1日間保持されます。
• 保存しない場合はstore=falseを設定します。ただし、これによりprevious_interaction_idとbackground=trueは無効になります。
• tools、system_instruction、generation_configはInteractionごとに適用されます。各ターンで再指定してください。
• マネージドエージェントでサンドボックスをプロビジョニングするには、environment="remote"（または環境ID／設定オブジェクト）が必要です。
• generateContentからの移行：スコープ、チェックリスト、変更前後のコード例については、references/migration.mdを読んでください。編集前に必ずユーザーにスコープを確認してください。
• モデルのアップグレード：モデル文字列を置き換えるだけで移行できます。非推奨モデル（gemini-2.0-*、gemini-1.5-*）は置き換える必要があります。references/migration.mdを参照してください。
• Gemini 3.7 FlashまたはGemini 3.5 Flash-Liteへの移行：スコープとチェックリストについては、references/migration.mdを読んでください。

クイックスタート

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="Tell me a short joke about programming."
)
print(interaction.output_text)

JavaScript/TypeScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.7-flash",
    input: "Tell me a short joke about programming.",
});
console.log(interaction.output_text);

レスポンスヘルパー

SDK は、一般的なアクセスパターンを簡略化するための便利なプロパティを Interaction レスポンスオブジェクト上に提供します。

プロパティ	型	説明
output_text	string | null	末尾の model_output ステップからの最後の連続したテキストのまとまり。モデルの最終出力に複数のテキストパートが含まれる場合は、結合されたテキストを返します。
output_image	Image | null	現在のレスポンスでモデルが生成した最後の画像。data（base64）と mime_type を持つオブジェクトを返します。
output_audio	Audio | null	現在のレスポンスでモデルが生成した最後の音声。data（base64）と mime_type を持つオブジェクトを返します。

ステートフルな会話

Python

interaction1 = client.interactions.create(
    model="gemini-3.7-flash",
    input="Hi, my name is Phil."
)
# Second turn — server remembers context
interaction2 = client.interactions.create(
    model="gemini-3.7-flash",
    input="What is my name?",
    previous_interaction_id=interaction1.id
)
print(interaction2.output_text)

JavaScript/TypeScript

const interaction1 = await client.interactions.create({
    model: "gemini-3.7-flash",
    input: "Hi, my name is Phil.",
});
const interaction2 = await client.interactions.create({
    model: "gemini-3.7-flash",
    input: "What is my name?",
    previous_interaction_id: interaction1.id,
});
console.log(interaction2.output_text);

Deep Research エージェント

高速なリサーチには deep-research-preview-04-2026 を、最大限の網羅性には deep-research-max-preview-04-2026 を使用してください。エージェントには background=True が必要です。

Python

import time

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Research the history of Google TPUs.",
    background=True
)
while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.output_text)
        break
    elif interaction.status == "failed":
        print(f"Failed: {interaction.error}")
        break
    time.sleep(10)

JavaScript/TypeScript

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

const client = new GoogleGenAI({});

// Start background research
const initialInteraction = await client.interactions.create({
    agent: "deep-research-preview-04-2026",
    input: "Research the history of Google TPUs.",
    background: true,
});

// Poll for results
while (true) {
    const interaction = await client.interactions.get(initialInteraction.id);
    if (interaction.status === "completed") {
        console.log(interaction.output_text);
        break;
    } else if (["failed", "cancelled"].includes(interaction.status)) {
        console.log(`Failed: ${interaction.status}`);
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 10000));
}

高度な機能: 協調プランニング、ネイティブな可視化、MCP 統合、ファイル検索、マルチモーダル入力。Deep Research ドキュメントを参照してください。

マネージドエージェント

マネージドエージェントは、Google がホストするサンドボックス化された Linux 環境内で実行されます。エージェントのコードを書く前に、マネージドエージェント クイックスタートを取得してください。

Antigravity エージェント

Antigravity エージェント（antigravity-preview-05-2026）は、汎用のマネージドエージェントです。コードの実行（Bash、Python、Node.js）、ファイルの管理、Web の閲覧、Google 検索の使用が可能です。機能、ツール、マルチモーダル入力、料金については Antigravity エージェント ドキュメントを参照してください。

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment="remote",
)

print(f"Environment ID: {interaction.environment_id}")
print(interaction.output_text)

JavaScript/TypeScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment: "remote",
});

console.log(`Environment ID: {interaction.environment_id}`);
console.log(interaction.output_text);

カスタムエージェント

カスタムエージェントの構築 ドキュメントを参照してください。

Python

agent = client.agents.create(
    id="code-reviewer",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
    },
)

# Invoke — each call forks the base environment
result = client.interactions.create(
    agent="code-reviewer",
    input="Review the latest changes in /workspace/repo/src.",
    environment="remote",
)
print(result.output_text)

JavaScript/TypeScript

const agent = await client.agents.create({
    id: "code-reviewer",
    base_agent="antigravity-preview-05-2026",
    system_instruction: "You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/my-org/backend",
                target: "/workspace/repo",
            }
        ],
    },
});

const result = await client.interactions.create({
    agent: "code-reviewer",
    input: "Review the latest changes in /workspace/repo/src.",
    environment: "remote",
});
console.log(result.output_text);

エージェントは client.agents.list()、client.agents.get(id=...)、client.agents.delete(id=...) で管理できます。

ストリーミング

stream=True を設定すると、増分のサーバー送信イベントを受信できます。各ストリームは次の順序に従います: interaction.created → (step.start → step.delta(s) → step.stop)+ → interaction.completed。

Python

for event in client.interactions.create(
    model="gemini-3.7-flash",
    input="Explain quantum entanglement in simple terms.",
    stream=True,
):
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)
    elif event.event_type == "interaction.completed":
        print(f"\n\nTotal Tokens: {event.interaction.usage.total_tokens}")

JavaScript/TypeScript

const stream = await client.interactions.create({
    model: "gemini-3.7-flash",
    input: "Explain quantum entanglement in simple terms.",
    stream: true,
});
for await (const event of stream) {
    if (event.event_type === "step.delta") {
        if (event.delta.type === "text") {
            process.stdout.write(event.delta.text);
        }
    } else if (event.event_type === "interaction.completed") {
        console.log(`\n\nTotal Tokens: ${event.interaction.usage.total_tokens}`);
    }
}

ツール、シンキング、エージェント、画像生成を伴うストリーミングについては、完全なストリーミングガイドを参照してください。

ドキュメントページ

コードを書く前に、以下の中から該当するページを必ず取得してください。 これらのホストされたドキュメントは、パラメータ、型、エッジケースに関する信頼できる情報源です — 上記の例だけに頼らないでください。

コアドキュメント:

• Interactions API の概要
• クイックスタート
• テキスト生成
• ストリーミング
• トークン
• API キー ツールと関数呼び出し：
• 関数呼び出し
• Google 検索
• コード実行
• URL コンテキスト
• ファイル検索
• ツールの組み合わせ
• コンピューター操作
• Maps Grounding

生成と出力：

• 構造化出力
• 思考
• 思考シグネチャ
• 画像生成
• 画像理解
• 動画の生成と編集（Omni Flash）
• 音声生成
• 音楽生成
• 埋め込み

マルチモーダル理解：

• 音声
• 音声の文字起こし
• 動画理解
• ドキュメント処理

ファイルとコンテキスト：

• ファイル
• ファイル入力方法
• キャッシュ
• メディア解像度

エージェント：

• エージェントの概要
• マネージドエージェントのクイックスタート
• Antigravity Agent
• エージェント環境
• カスタムエージェントの構築
• Deep Research

高度な機能：

• 最新モデル（3.7 Flash と 3.5 Flash-Lite）
• Flex Inference
• Priority Inference

API リファレンス：

• API リファレンス
• OpenAPI 仕様
• 2026 年 5 月の破壊的変更に関する移行ガイド

データモデル

Interaction のレスポンスには steps が含まれます。これは、インタラクションのターンを構造化されたタイムラインとして表す、型付きステップオブジェクトの配列です。

ステップの種類

ユーザーステップ：

• user_input：ユーザー入力（テキスト、音声、マルチモーダル）。content 配列を含みます。

モデル／サーバーステップ：

• model_output：モデルの最終生成結果。text、image、audio などを含む content 配列を含みます。
• thought：モデルの推論／思考の連鎖。必須の signature フィールドと、任意の summary を含みます。
• function_call：ツール呼び出しリクエスト（id、name、arguments）。
• function_result：返送するツールの結果（call_id、name、result）。
• google_search_call / google_search_result：Google Search ツールのステップ。signature フィールドを含む場合があります。
• code_execution_call / code_execution_result：コード実行ツールのステップ。signature フィールドを含む場合があります。
• url_context_call / url_context_result：URL コンテキストツールのステップ。signature フィールドを含む場合があります。
• mcp_server_tool_call / mcp_server_tool_result：リモート MCP ツールのステップ。
• file_search_call / file_search_result：ファイル検索ツールのステップ。signature フィールドを含む場合があります。

コンテンツの種類（model_output および user_input ステップの content 配列内）

• text：テキストコンテンツ（text フィールド）
• image / audio / document / video：data、mime_type、または uri を含むコンテンツ

ストリーミングイベントの種類

イベント	説明
interaction.created	インタラクションが作成されました。メタデータを含みます。
interaction.status_update	インタラクションレベルのステータス変更です。
step.start	新しいステップが開始されます。ステップの type と初期メタデータを含みます。
step.delta	現在のステップの増分データです。型付きの delta オブジェクトを含みます。
step.stop	ステップが完了しました。index を含みます。
interaction.completed	インタラクションが終了しました。最終的な usage を含みます。

Delta の種類

Delta の種類	親ステップ	説明
text	model_output	増分テキストトークンです。
audio	model_output	音声チャンク（base64）です。
image	model_output	画像チャンク（base64）です。
thought_summary	thought	思考の要約テキストです。
thought_signature	thought	思考の検証に使用する不透明な署名です。

ステータス値： completed、in_progress、requires_action、failed、cancelled