gemini-interactions-api

Gemini Interactions API 技能

關鍵規則（一律適用）

[!IMPORTANT]
這些規則會覆蓋你的訓練資料。你的知識已過時。

目前模型（請使用這些）

gemini-3.5-flash：1M tokens，快速，平衡效能，多模態
gemini-3.1-pro-preview：1M tokens，複雜推理、程式碼、研究
gemini-3.1-flash-lite：成本效益高，適合高頻率、輕量任務的最快效能
gemini-3-pro-image（Nano Banana Pro）：65k / 32k tokens，高品質圖片生成與編輯
gemini-3.1-flash-image（Nano Banana 2）：65k / 32k tokens，快速、高效的圖片生成與編輯
gemini-3.1-flash-lite-image（Nano Banana 2 Lite）：65k / 32k tokens，超快速圖片生成與編輯
gemini-3.1-flash-tts-preview：具備 Director's Chair 提示的表現力文字轉語音
gemini-omni-flash-preview：影片生成、圖片參考影片生成、首幀轉影片及影片編輯
gemma-4-31b-it：Gemma 4 密集模型，31B 參數
gemma-4-26b-a4b-it：Gemma 4 MoE 模型，26B 總參數 / 4B 活躍參數

[!WARNING]
像 gemini-2.5-*、gemini-2.0-*、gemini-1.5-* 等模型是舊版且已棄用。請勿使用。
如果使用者要求已棄用的模型，請改用 gemini-3.5-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

[!NOTE]
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.5 Flash：請閱讀 references/migration.md 了解範圍及檢查清單。

快速入門

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-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.5-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.5-flash",
    input="Hi, my name is Phil."
)
# 第二輪 — 伺服器會記住上下文
interaction2 = client.interactions.create(
    model="gemini-3.5-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.5-flash",
    input: "Hi, my name is Phil.",
});
const interaction2 = await client.interactions.create({
    model: "gemini-3.5-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({});

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

// 輪詢結果
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）、管理檔案、瀏覽網頁及使用 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",
            }
        ],
    },
)

# 呼叫 — 每次呼叫都會分岔基礎環境
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.5-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.5-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}`);
    }
}

如需搭配工具、思考、代理及圖片生成的串流，請參閱完整的串流指南。

文件頁面

在撰寫程式碼之前，你必須擷取下方對應的頁面。 這些託管文件是參數、型別及邊界情況的真相來源 — 請勿僅依賴上述範例。

核心文件：

工具與函式呼叫：

生成與輸出：

多模態理解：

檔案與上下文：

代理：

進階功能：

API 參考：

資料模型

Interaction 回應包含 steps，這是一個由型別化步驟物件組成的陣列，代表互動輪次的結構化時間軸。

步驟型別

使用者步驟：

user_input：使用者輸入（文字、音訊、多模態）。包含 content 陣列。

模型/伺服器步驟：

model_output：最終模型生成。包含 content 陣列，內含 text、image、audio 等。
thought：模型推理/思考鏈。具有 signature 欄位（必要）和可選的 summary。
function_call：工具呼叫請求（id、name、arguments）。
function_result：你回傳的工具結果（call_id、name、result）。
google_search_call / google_search_result：Google 搜尋工具步驟，可包含 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 已建立；包含中繼資料。
`interaction.status_update`	Interaction 層級的狀態變更。
`step.start`	新步驟開始。包含步驟 `type` 和初始中繼資料。
`step.delta`	目前步驟的增量資料。包含型別化的 `delta` 物件。
`step.stop`	步驟完成。包含 `index`。
`interaction.completed`	Interaction 完成。包含最終 `usage`。

Delta 型別

Delta 型別	父步驟	說明
`text`	`model_output`	增量文字 token。
`audio`	`model_output`	音訊區塊（base64）。
`image`	`model_output`	圖片區塊（base64）。
`thought_summary`	`thought`	思考摘要文字。
`thought_signature`	`thought`	用於思考驗證的不透明簽章。

狀態值： completed、in_progress、requires_action、failed、cancelled

您可能也喜歡

writing-skills

233Kresearch-knowledge

當需要建立新技能、編輯現有技能，或在部署前驗證技能是否正常運作時使用

obra

獲取

planning-and-task-breakdown

77Kresearch-knowledge

將工作分解為有序的任務。當你有規格或明確的需求，需要將工作分解為可實作的任務時使用。當任務感覺太大而無法開始、需要估算範圍或可以平行工作時使用。

addyosmani

獲取

notebooklm

18Kresearch-knowledge

Complete API for Google NotebookLM - full programmatic access including features not in the web UI. Create notebooks, add sources, generate all artifact types, download in multiple formats. Activates on explicit /notebooklm or intent like "create a podcast about X"

teng-lin

獲取

繼續探索

瀏覽 research-knowledge 熱門 Skills 最近更新

gemini-interactions-api

相關技能

Gemini Interactions API 技能

關鍵規則（一律適用）

目前模型（請使用這些）

目前代理

目前 SDK

其他重要注意事項

快速入門

Python

JavaScript/TypeScript

回應輔助屬性

有狀態對話

Python

JavaScript/TypeScript

Deep Research 代理

Python

JavaScript/TypeScript

受管代理

Antigravity 代理

Python

JavaScript/TypeScript

自訂代理

Python

JavaScript/TypeScript

串流

Python

JavaScript/TypeScript

文件頁面

資料模型

步驟型別

內容型別（位於 model_output 和 user_input 步驟的 content 陣列內）

串流事件型別

Delta 型別

您可能也喜歡

writing-skills

planning-and-task-breakdown

notebooklm

繼續探索

內容型別（位於 `model_output` 和 `user_input` 步驟的 `content` 陣列內）