Gemini API架构升级:Interactions GA与Carbon Agent实战
Gemini 4 Carbon 上线,Interactions API 正式 GA,支持后台异步任务、Managed Agents 与 MCP 接入,详解接口差异、Python 示例、定价与多模型接入方案。

2026 年 11 月 10 日,Google DeepMind 正式开放 Gemini 4 Carbon,面向开发者和企业提供 API 调用能力。这款新模型主要面向复杂软件工程、科学研究、多步骤推理和长周期 Agent 工作流,支持最高 1M Token 上下文,并具备文本、图片、音频、视频和 PDF 等多模态处理能力。
但如果只关注新模型的参数和价格,可能会忽略 Google 此前已经完成的一项重要开发者接口升级。
2026 年 6 月,Google 宣布 Gemini Interactions API 正式进入 General Availability(GA)阶段,并将其确定为 Gemini 模型与 Agent 交互的主要 API 接口。与传统的 generateContent 请求响应模式不同,Interactions API 开始将对话状态、工具执行、后台任务和模型输出统一组织成可追踪的交互记录。
这意味着 Gemini API 的开发方式正在发生变化:开发者不再只是向模型提交 Prompt、等待文本返回,还可以通过统一接口创建 Agent 任务,让模型在远程环境中执行代码、访问工具、管理文件,并在后台持续完成较长的工作流程。
对于正在开发 AI 编程助手、企业自动化系统和多模型 Agent 的团队来说,这次变化比单纯增加一个新模型更值得研究。
本文将从 Gemini 4 Carbon 最新发布、Interactions API 架构、后台执行机制、MCP 工具连接、Python 接入和成本管理几个方面,分析 Google Gemini API 的最新技术变化。
一、Gemini API 最新消息:Gemini 4 Carbon 开放,Agent 能力成为重点
2026 年 11 月 10 日,Google 正式公布 Gemini 4 Carbon。
根据 Google DeepMind 官方公告,Carbon 是 Gemini 4 系列中面向高复杂度任务的推理模型,重点覆盖以下方向:
- 复杂软件工程与多步骤代码调试。
- 长周期 AI Agent 工作流。
- 科学研究与数学推理。
- 网络安全防御。
- 企业知识工作和复杂自动化。
官方强调,Gemini 4 Carbon 能够在复杂任务中使用更多 Token 进行推理,并通过持续验证循环处理难度较高的问题。它与 Gemini 4 Argon 的定位有所区别:Argon 更侧重常规软件工程、知识工作和效率,而 Carbon 面向需要更深层推理、较长执行过程和复杂验证的任务。
Gemini 4 Carbon 核心参数
表格
| 参数 | 官方信息 |
|---|---|
| 模型名称 | Gemini 4 Carbon |
| API Model ID | gemini-4-carbon |
| 上下文窗口 | 1M Token |
| 长输出能力 | 最长可达 1M Token |
| 输入模态 | 文本、图片、音频、视频、PDF |
| 主要方向 | 复杂编程、科学推理、Agent |
| 免费层 | 不支持 |
| API 开放渠道 | Google AI Studio 付费层、Gemini API |
这里的 1M Token 长输出能力是官方介绍的长解码能力,不代表所有普通请求都会默认输出 100 万 Token。实际请求还需要遵守对应模型和接口的输出配置限制。
为什么 Carbon 更适合复杂 Agent?
以一个企业软件开发任务为例。用户希望 AI 自动完成一个现有系统的权限模块改造,任务可能包含:
- 阅读现有项目结构。
- 检查身份认证和权限校验逻辑。
- 找出多个模块之间的依赖。
- 制定修改计划。
- 修改相关源代码。
- 执行自动化测试。
- 分析测试失败原因。
- 再次修改并输出验收报告。
这类任务不是一次模型回答就能完成的。模型需要在多个执行阶段保持任务目标一致,并能够根据工具返回结果调整后续操作。Gemini 4 Carbon 面向长周期 Agent 工作流的定位,正是为了处理这种复杂场景。
不过,模型的推理能力和 Agent 的实际执行能力仍然需要区分。Carbon 负责模型推理,文件操作、代码运行、网络访问和权限控制则需要由相应的 Agent 环境提供。
二、Gemini Interactions API 正式 GA:为什么 Google 要重新设计接口?
传统 Gemini API 主要使用 generateContent 接口。这种接口采用典型的请求响应模式:
用户提交 Prompt
|
v
发送 API 请求
|
v
Gemini 生成内容
|
v
返回模型结果这种方式非常适合普通问答、文本生成、图片理解和结构化输出。但当应用开始接入 Agent 后,原有模式就会出现一些工程问题。
例如,一个任务需要连续调用多个工具,每次工具执行完成后,还需要把结果重新发送给模型。如果任务持续几十分钟,应用还需要处理连接超时、历史记录保存、工具状态和请求恢复。开发者必须自行维护大量上下文和任务调度逻辑。
Interactions API 的设计目标,就是将这些能力整合到统一的交互资源中。
根据 Google 官方公告,Interactions API 在 2025 年 12 月进入公开测试阶段,并于 2026 年 6 月正式 GA。目前 Google 已经将它设为 Gemini API 官方文档的默认接口,并建议新项目优先使用。
1. 从 GenerateContent 到 Interaction 对象
传统接口主要围绕消息内容组织请求。Interactions API 则引入了 Interaction 资源。
每个 Interaction 代表一次完整的交互或任务记录,内部可以包含:
- 用户输入。
- 模型推理步骤。
- 函数调用。
- 工具返回结果。
- 最终模型输出。
这些信息以有序步骤的形式保存。
这种设计有一个直接优势:开发者可以看到 Agent 在任务执行过程中调用了什么工具、得到了什么结果,以及最终输出了什么内容。
例如,一个代码分析 Agent 先调用文件搜索工具,再调用代码执行工具,最后生成报告。在传统模式下,应用需要自己组织这些请求和返回内容;Interactions API 则可以将多个执行步骤组织在同一个交互资源中,便于调试、追踪和后续处理。
2. 服务端上下文管理减少重复传输
多轮对话最容易产生的问题,就是上下文不断增长。
假设用户要求 Gemini 分析一个项目,第一轮提供了项目目录、配置文件和业务说明;第二轮要求模型检查数据库调用;第三轮要求它继续修改权限逻辑。如果每次请求都重新提交完整历史记录,输入 Token 会持续增加。
Interactions API 支持通过 previous_interaction_id 关联上一轮交互。
示意代码:
from google import genai
client = genai.Client()
# 第一轮
turn1 = client.interactions.create(
model="gemini-4-carbon",
input="分析这个项目的身份认证模块。"
)
# 第二轮:继续上一轮任务
turn2 = client.interactions.create(
model="gemini-4-carbon",
input="继续检查权限校验逻辑。",
previous_interaction_id=turn1.id
)
print(turn2.output_text)在这种模式下,开发者不需要每次重新提交完整对话历史,服务端可以根据交互 ID 找到此前保存的上下文。
需要注意,previous_interaction_id 关联的是历史交互内容,并不意味着所有请求参数都会自动继承。例如,工具定义、系统指令和生成配置等交互级参数,需要在后续请求中按照需要重新指定。此外,服务端状态管理可以提高隐式缓存的利用机会,但不意味着所有请求都必然命中缓存。
三、后台执行:Gemini API 如何处理长时间运行的 Agent?
这是 Interactions API 对开发者最有价值的改进之一。
传统 HTTP 请求通常需要保持客户端与服务端之间的连接。如果 Agent 需要执行代码、安装依赖、读取多个文件并完成复杂分析,任务可能持续较长时间。在这种情况下,持续保持 HTTP 连接并不可靠。网络断开、客户端超时或者服务器重启,都可能影响任务结果的获取。
Google 为 Interactions API 提供了后台执行机制。开发者可以设置:
background=True让模型任务在服务端异步执行。API 会先返回 Interaction ID,客户端之后可以通过 ID 查询任务状态,而不必持续占用一个 HTTP 连接。
一个后台执行工作流
提交 Agent 任务
|
v
Interactions API
|
v
立即返回 Interaction ID
|
v
服务端继续执行
|
v
模型推理与工具调用
|
v
执行完成或失败
|
v
客户端查询任务状态
|
v
获取最终结果这种模式尤其适合:
- 大型代码仓库分析。
- 长篇研究报告生成。
- 多步骤文件处理。
- 自动化测试和调试。
- 企业内部数据分析。
- 需要持续调用外部工具的 Agent。
Python 后台执行示例
首先安装官方 SDK:
pip install -U google-genai配置 API Key:
export GEMINI_API_KEY="YOUR_API_KEY"示例代码:
import os
import time
from google import genai
client = genai.Client(
api_key=os.environ["GEMINI_API_KEY"])
# 1. 创建后台任务
interaction = client.interactions.create(
model="gemini-4-carbon",
input=(
"分析一个大型Python项目的模块依赖,"
"识别循环依赖和潜在的架构问题,"
"最终生成Markdown报告。"
),
background=True
)
interaction_id = interaction.id
print("任务已创建:", interaction_id)
# 2. 查询执行状态
while True:
result = client.interactions.get(
interaction_id
)
print("当前状态:", result.status)
if result.status == "completed":
print("执行完成:")
print(result.output_text)
break
if result.status not in ("in_progress",):
raise RuntimeError(
f"任务结束,状态:{result.status}"
)
time.sleep(5)这段代码展示了后台任务的基本使用方式。实际生产环境还需要增加:
- 任务超时控制。
- 查询频率限制。
- 任务状态持久化。
- 网络异常处理。
- 重复任务识别。
- 结果存储和回调通知。
尤其是任务 ID,应该保存在业务数据库中,而不是只放在进程内存里。否则,后端服务重启后,应用可能无法继续追踪已经提交的任务。
四、Managed Agents:Gemini API 开始提供远程执行环境
后台执行解决的是任务如何持续运行。Managed Agents 进一步解决了 Agent 在哪里运行、如何使用工具的问题。
Google 官方公布的 Managed Agents 能力,允许开发者通过 API 创建远程 Linux 沙箱环境。在这个环境中,Agent 可以根据任务需要执行:
- 代码运行。
- 软件包安装。
- 文件管理。
- 网页信息检索。
- 工具调用。
- 多步骤任务执行。
这意味着开发者不必为每个简单的 Agent 项目都从零搭建完整的执行环境。
1. 远程沙箱与普通模型调用有什么区别?
普通模型 API 主要负责接收输入并返回生成结果。Managed Agents 则可以将模型推理和实际执行环境结合起来。
例如,用户要求 Agent 检查一个 GitHub 项目中的 TODO 注释,并根据模块和优先级生成报告。Agent 可以先克隆项目,再扫描代码文件,整理任务信息,最后生成 Markdown 报告。整个过程中,模型负责理解和规划,远程沙箱负责执行具体操作。
但需要注意,远程沙箱并不等于可以不受限制地访问所有网络资源和系统文件。开发者仍然需要配置网络访问规则、凭证权限和允许执行的工具。
2. 支持 Remote MCP 连接内部系统
MCP(Model Context Protocol)是用于连接模型与外部工具、数据源的开放协议。企业可以通过 MCP 将内部业务系统暴露为模型能够调用的工具,例如:
- 内部数据库查询服务。
- 监控和日志系统。
- 工单系统。
- 企业知识库。
- 项目管理系统。
Google Managed Agents 支持连接 Remote MCP Server。
示例:
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
agent: "antigravity-preview-05-2026",
input: "检查认证服务最近的延迟异常,并关联相关代码提交。",
environment: "remote",
tools: [
{ type: "google_search" },
{ type: "code_execution" },
{
type: "mcp_server",
name: "internal_telemetry",
url: "https://mcp.internal.example.com/mcp"
}
]
});
console.log(interaction.output_text);这里的 MCP 地址只是官方示例中的占位地址,实际使用时需要替换成企业已经部署并授权的 MCP 服务。这种方式可以减少开发者为每个内部系统单独编写工具适配层的工作。不过,远程 MCP 接入仍然需要处理认证、网络隔离、调用权限和数据访问范围。
3. 多工具组合不再局限于单一调用链
Interactions API 还支持将 Google Search、Google Maps 等内置工具与开发者自定义函数组合在同一个请求中。
例如,一个企业销售 Agent 可以先使用 Google Search 收集公开市场信息,再调用内部库存查询函数,最后根据两个工具的结果生成销售建议。在传统架构中,开发者可能需要分别管理搜索请求、函数调用和上下文传递;现在可以在同一个交互过程中组织这些步骤。
这对于构建多工具 Agent 有实际意义,但并不意味着模型能够绕过工具本身的权限控制。
五、Gemini 4 Carbon API 价格:11 月与 12 月存在明显差异
除了模型能力,开发者还需要关注此次发布对应的 API 定价。根据 Google AI Studio 官方价格页面,Gemini 4 Carbon 当前采用付费层计费,免费层暂不开放。
截至 2026 年 11 月 30 日,官方公布的标准模式价格如下:
表格
| 计费项目 | 11 月 30 日前 | 12 月 1 日起 |
|---|---|---|
| 输入 / 百万 Token | $2 | $4 |
| 输出 / 百万 Token | $10 | $20 |
| 缓存输入 / 百万 Token | $0.10 | $0.20 |
价格单位均为美元。也就是说,12 月 1 日起,Carbon 的标准输入和输出价格将调整为当前价格的两倍。
这里有几个成本细节需要注意。
第一,思考 Token 也会计入输出费用。 Carbon 属于推理模型,模型内部思考 Token 并不是免费的。官方明确将其计入输出 Token 计费。因此,复杂任务即使最终只返回一份较短的报告,也可能产生较高的输出费用。
第二,Grounding 工具可能产生额外费用。 Google Search Grounding 在付费层每月提供共享的 5,000 次免费搜索请求额度,超出后为每 1,000 次请求 14 美元。需要注意,一次模型请求可能触发多次搜索查询,计费以实际搜索请求为准。
第三,Flex 和 Batch 不能混为一谈。 Google 当前提供不同的推理服务等级:
- Standard:常规服务。
- Flex:以更低成本换取非优先执行。
- Priority:优先处理,面向对延迟敏感的场景。
官方在 Interactions API GA 公告中表示,Flex 可以实现最高约 50% 的成本降低。但 Flex 并不是所有请求都应该默认使用的模式。对于实时客服和交互式编程,响应时延可能比单次成本更加重要。
另外,Batch API 虽然在 Gemini API 付费层提供约 50% 的价格优惠,但截至当前 Interactions API 功能说明,Batch API 尚未列入该接口的支持能力。如果项目需要批量处理离线任务,仍应根据官方 Batch API 的适用接口选择实现方式,不能直接把 Batch 参数放入 Interactions API 请求中。
六、Interactions API 与 generateContent 如何选择?旧项目需要立即迁移吗?
这是开发者升级时最容易遇到的问题。Google 推荐新项目使用 Interactions API,但没有宣布 generateContent 停止服务。两种接口目前仍然具有不同的使用场景。
表格
| 对比维度 | generateContent | Interactions API |
|---|---|---|
| 核心模式 | 请求与响应 | 交互与任务资源 |
| 对话历史 | 通常由客户端管理 | 支持服务端状态 |
| 多轮上下文 | 重新组织历史消息 | previous_interaction_id |
| 长任务后台执行 | 需要自行组织执行流程 | 原生支持 |
| 工具调用 | 支持 | 支持 |
| 执行步骤追踪 | 需要自行记录 | 原生 Interaction Steps |
| Managed Agents | 不属于该接口的核心能力 | 支持 |
| 典型用途 | 普通生成和成熟业务接口 | 长周期 Agent 和复杂交互 |
对于现有的文本生成应用,如果目前运行稳定,没有必要仅仅因为新接口发布就立即迁移。但如果正在开发具备以下特点的系统,就值得优先研究 Interactions API:
- 多轮复杂推理。
- 多工具连续调用。
- 需要后台运行的 Agent。
- 需要保留任务执行记录。
- 需要连接远程 MCP 服务。
- 需要统一管理模型和 Agent 的应用。
迁移时需要检查的三个问题
- 对话结构需要重新设计。
旧接口通常围绕 messages 和 contents 组织数据。Interactions API 则采用步骤化的数据结构。迁移时需要重新处理用户输入、模型输出、工具调用和工具返回结果之间的关系。
- 不要假设所有参数都能直接映射。
旧接口中的 generationConfig、工具定义和多模态输入,需要按照新接口对应字段进行转换。特别是工具调用历史,不能只保存最终文本,否则后续交互可能丢失必要的执行信息。
- 检查数据保留和隐私要求。
Interactions API 默认会保存交互资源。根据官方文档:
- 付费层保留 55 天。
- 免费层保留 1 天。
开发者可以通过 store=false 关闭交互存储。但是,这会同时失去基于 previous_interaction_id 的服务端上下文延续能力,并且不能与后台执行一起使用。因此,不能简单地认为关闭存储不会影响其他功能。对于企业内部系统,应当结合数据敏感等级、日志保留周期和业务审计要求决定是否启用服务端状态管理。
七、多模型 API 如何接入 Gemini 4 Carbon?企业开发架构需要注意什么?
当一个应用只使用 Gemini 时,直接调用官方 API 通常比较简单。但如果系统同时使用 Gemini、DeepSeek、Qwen 和其他模型,就需要处理不同供应商之间的接口差异。
例如,一个 AI 编程平台可能使用:
- Gemini 4 Carbon 处理复杂代码分析。
- DeepSeek 处理常规代码任务。
- Qwen 处理部分结构化知识任务。
- Codex 负责工程文件操作和测试执行。
不同模型的 API 参数、工具调用方式、上下文机制和计费结构并不完全一致。这时可以在应用层和模型层之间增加统一 API 管理层。例如,使用 KoalaAPI 这样的多模型 API 聚合服务,可以集中管理已经接入的模型和 API 凭证,减少多个供应商之间重复配置的工作。
不过需要明确:统一 API 网关并不等于完整的 Agent 运行环境。Interactions API 的服务端状态、Managed Agents、Remote MCP 和后台执行等功能,仍然需要确认具体接口是否得到支持。
在实际接入 Gemini 4 Carbon 前,应该核实以下内容:
- 模型目录中是否已经提供准确的 gemini-4-carbon 标识。
- 是否支持 Gemini 对应的原生接口。
- 是否能够正确传递多模态内容。
- 是否支持服务端状态与 previous_interaction_id。
- 是否能够正确统计思考 Token 和工具调用费用。
- 是否支持后台任务及其状态查询。
不能因为某个平台兼容 OpenAI SDK,就认为它一定支持 Gemini 的全部原生能力。对于复杂 Agent 项目,建议先通过官方 API 验证完整工作流,再决定是否将模型调用纳入统一接入层。
八、总结:Gemini API 的下一阶段是模型与 Agent 一体化
Gemini API 最近的变化,实际上包含两个相互关联的方向。
一方面,Gemini 4 Carbon 于 2026 年 11 月 10 日开放 API 调用,将重点放在复杂推理、软件工程和长周期 Agent 工作流上。
另一方面,Interactions API 已经从公开测试进入 GA,Google 正在将模型调用、上下文管理、工具执行和后台任务整合到统一的接口体系中。
对于开发者来说,这意味着 Gemini API 的使用方式正在从单纯的模型请求,逐步扩展到完整的 Agent 任务管理。如果项目只是普通文本生成,generateContent 仍然可以继续使用;如果项目涉及长周期任务、多轮工具调用、服务端上下文和远程执行环境,那么 Interactions API 更值得优先研究。
同时,开发者也需要关注 Carbon 在 12 月 1 日的价格调整,以及 Interactions API 在 Batch、缓存和函数调用方面的功能边界。
未来多模型应用的技术竞争,不只是比较 Gemini、DeepSeek、Qwen 等模型的回答质量,还要看它们能否在统一的业务架构中稳定完成推理、工具调用和任务交付。这也是此次 Gemini API 架构升级更值得关注的地方。

