gemini-interactions-api

Name: gemini-interactions-api
Author: google-gemini

github.com/google-gemini开发4.4k12.3k 次安装2 周前更新

代码仓库

关于 gemini-interactions-api

面向使用 Python 和 JavaScript/TypeScript SDK 的 Gemini Interactions API 开发者，介绍交互状态、流式响应、Agent 及从旧版 generateContent API 迁移的方法。

主要功能

01当前模型与 SDK 指引
02有状态交互
03流式响应示例
04托管与自定义 Agent
05generateContent 迁移指引

适用场景

01创建 Interactions API 请求
02在多轮交互中保留上下文
03流式接收生成结果
04从 generateContent 迁移

MCP 相关

技能介绍了 Interaction 数据模型中的远程 MCP 工具调用与结果步骤，并将 MCP 集成列为高级能力。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google-gemini/gemini-skills --skill gemini-interactions-api

安装后在 Claude Code 中输入/gemini-interactions-api确认已加载。

附带文件references/migration.md

详细介绍

Gemini Interactions API 技能

关键规则（始终适用）

重要

这些规则优先于你的训练数据。你的知识已经过时。

当前模型（使用这些模型）

gemini-3.7-flash：1M 个 token，速度快，适用于 Agent 和多模态任务，性能均衡
gemini-3.5-flash-lite：1M 个 token，速度最快、成本最低的 3.5 模型，适用于高吞吐量执行
gemini-3.1-pro-preview：1M 个 token，适用于复杂推理、编码和研究
gemini-3.1-flash-lite：成本高效、性能最快，适用于高频轻量级任务
gemini-3.5-transcribe：快速语音转文本，支持智能和逐字模式
gemini-3-pro-image（Nano Banana Pro）：65k / 32k 个 token，高质量图像生成与编辑
gemini-3.1-flash-image（Nano Banana 2）：65k / 32k 个 token，快速高效的图像生成与编辑
gemini-3.1-flash-lite-image（Nano Banana 2 Lite）：65k / 32k 个 token，超快速图像生成与编辑
gemini-3.1-flash-tts-preview：富有表现力的文本转语音，支持 Director's Chair 提示词
gemini-omni-1.1-flash：视频生成、首帧转视频、首尾帧过渡、视频扩展（最长 40s）、视频编辑和参考引导生成
gemma-4-31b-it：Gemma 4 稠密模型，31B 参数
gemma-4-26b-a4b-it：Gemma 4 MoE 模型，26B 总参数 / 4B 激活参数
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，并说明替换情况。

当前 Agent

antigravity-preview-05-2026：Antigravity Agent — 通用托管 Agent，可在沙盒 Linux 环境中执行代码、管理文件并访问 Web
deep-research-preview-04-2026：Deep Research — 快速、交互式
deep-research-max-preview-04-2026：Deep Research Max — 最大程度详尽
自定义 Agent：通过 client.agents.create() 创建自己的 Agent

当前 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 范围、参数和边缘情况。
默认情况下，交互会被存储（store=true）。付费层级保留 55 天，免费层级保留 1 天。
设置 store=false 可选择不存储，但这会禁用 previous_interaction_id 和 background=true。
tools、system_instruction 和 generation_config 的作用范围仅限当前交互，每轮都要重新指定。
托管 Agent 需要设置 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);

深度研究 Agent

快速研究请使用 deep-research-preview-04-2026，追求最全面的研究请使用 deep-research-max-preview-04-2026。Agent 需要设置 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 集成、文件搜索、多模态输入。请参阅深度研究文档。

托管 Agent

托管 Agent 运行在由 Google 托管的沙盒 Linux 环境中。编写 Agent 代码之前，请先查看托管 Agent 快速入门。

Antigravity Agent

Antigravity Agent（antigravity-preview-05-2026）是通用托管 Agent。它可以执行代码（Bash、Python、Node.js）、管理文件、浏览网页并使用 Google Search。有关功能、工具、多模态输入和定价，请参阅 Antigravity Agent 文档。

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);

自定义 Agent

请参阅构建自定义 Agent 文档。

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=...) 管理 Agent。

流式传输

设置 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}`);
    }
}

有关使用工具、思考、Agent 和图片生成进行流式传输的信息，请参阅完整的流式传输指南。

文档页面

编写代码前，必须先获取下方对应的页面。 这些托管文档是参数、类型和边缘情况的权威来源——不要仅依赖上面的示例。

核心文档：

生成与输出：

多模态理解：

文件与上下文：

Agent：

高级功能：

API 参考：

数据模型

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`。

增量类型

增量类型	父步骤	描述
`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

支持 Markdown

登录后评论

基本信息

作者: google-gemini
仓库: google-gemini/gemini-skills
分类: 开发
安装次数: 12,350
GitHub Stars: 4,353

报告问题

gemini-interactions-api

关于 gemini-interactions-api

主要功能

适用场景

MCP 相关

安装

详细介绍

Gemini Interactions API 技能

关键规则（始终适用）

当前模型（使用这些模型）

当前 Agent

当前 SDK

重要补充说明

快速入门

Python

JavaScript/TypeScript

响应辅助属性

有状态对话

Python

JavaScript/TypeScript

深度研究 Agent

Python

JavaScript/TypeScript

托管 Agent

Antigravity Agent

Python

JavaScript/TypeScript

自定义 Agent

Python

JavaScript/TypeScript

流式传输

Python

JavaScript/TypeScript

文档页面

数据模型

步骤类型

内容类型（model_output 和 user_input 步骤中 content 数组内的类型）

流式事件类型

增量类型

评论

内容类型（`model_output` 和 `user_input` 步骤中 `content` 数组内的类型）