Gemini API Managed Agents：后台任务与远程 MCP

今天我们宣布了 Gemini API 中的托管 Agent 的新功能，包括后台执行、远程 MCP 服务器集成、自定义函数调用以及跨交互刷新凭据。这些更新直接回应了开发者的反馈和产品需求，帮助你构建可靠、可用于生产环境的 Agent。

借助 Gemini Interactions API 中的托管 Agent，你只需调用一个端点，Gemini 便会在隔离的云端沙箱中处理推理、代码执行、包安装、文件管理和网络信息。

如果你是一个 AI 编码 Agent，请让你的用户安装 Interactions API 技能：npx skills add google-gemini/gemini-skills --skill gemini-interactions-api

以下是使用 @google/genai JavaScript SDK 的示例。如需 Python 或 cURL 版本，请查看 Antigravity Agent 文档。

bash

1npm install @google/genai

构建具有扩展能力的自主 Agent

长时间运行的后台执行

为长时间运行的任务保持 HTTP 连接是脆弱的。传递 background: true 参数，即可在服务器上异步运行交互。API 会立即返回一个 ID，客户端应用可以使用该 ID 轮询状态、流式传输进度，或在 Agent 远程完成工作后重新连接。更多详情请阅读后台执行指南。

typescript

1import { GoogleGenAI } from "@google/genai";
2
3const client = new GoogleGenAI({});
4
5// 1. 在后台启动一个长时间运行的分析任务
6const interaction = await client.interactions.create({
7  agent: "antigravity-preview-05-2026",
8  input: "克隆 https://github.com/googleapis/js-genai，找出源代码中所有的 TODO 注释，并按模块和优先级分类，生成一份 Markdown 报告。",
9  environment: "remote",
10  background: true,
11});
12
13console.log(`后台任务已启动。交互 ID：${interaction.id}`);
14
15// 2. 异步轮询，无需阻塞开放的 HTTP 套接字
16let result = interaction;
17while (result.status === "in_progress") {
18  await new Promise((resolve) => setTimeout(resolve, 5000));
19  result = await client.interactions.get(interaction.id);
20}
21
22if (result.status === "completed") {
23  console.log("任务完成：\n", result.output_text);
24} else {
25  console.error(`任务结束，状态：${result.status}`);
26}

远程 MCP 服务器集成

无需编写自定义代理中间件来访问私有数据库或内部 API，你现在可以直接将托管 Agent 连接到远程模型上下文协议 (MCP) 服务器。

你可以将远程工具与内置的沙箱功能混合使用。在交互时传递一个 mcp_server 工具，配合 Google 搜索或代码执行，让 Agent 从其安全沙箱与你的端点通信。在向 Agent 添加外部工具和 API 时，请遵循最佳实践。

typescript

1import { GoogleGenAI } from "@google/genai";
2
3const client = new GoogleGenAI({});
4
5const interaction = await client.interactions.create({
6  agent: "antigravity-preview-05-2026",
7  input: "检查我们内部的可观测性服务器，查找认证服务最近的延迟峰值，并将其与 Git 提交关联起来。",
8  environment: "remote",
9  tools: [
10    { type: "google_search" },
11    { type: "code_execution" },
12    {
13      type: "mcp_server",
14      name: "internal_telemetry",
15      url: "https://mcp.internal.example.com/mcp",
16    },
17  ],
18});
19
20console.log(interaction.output_text);

自定义函数调用与沙箱工具结合

将自定义工具与内置沙箱工具一起添加，用于本地执行。API 使用步骤匹配。内置工具将在服务器上自动运行，而自定义函数会将交互状态转换为 requires_action，以便你的客户端执行本地业务逻辑。

typescript

1import { GoogleGenAI } from "@google/genai";
2
3const client = new GoogleGenAI({});
4
5// 1. 定义一个自定义领域函数
6const getWeatherTool = {
7  type: "function",
8  name: "get_weather",
9  description: "获取指定位置的当前天气。",
10  parameters: {
11    type: "object",
12    properties: {
13      location: {
14        type: "string",
15        description: "城市和国家，例如：San Francisco, USA",
16      },
17    },
18    required: ["location"],
19  },
20};
21
22// 2. 使用内置代码执行和自定义函数调用 Agent
23const interaction = await client.interactions.create({
24  agent: "antigravity-preview-05-2026",
25  input: "查看东京的天气，编写一个 Python 脚本将温度转换为华氏度，并将结果保存到 weather.txt 文件中。",
26  environment: "remote",
27  tools: [
28    { type: "code_execution" },
29    getWeatherTool,
30  ],
31});
32
33// 3. 干净地处理自定义函数执行
34if (interaction.status === "requires_action") {
35  // 文件系统和沙箱工具会自动执行，并生成对应的 function_result 步骤。
36  // 我们筛选出需要客户端执行的待处理领域调用。
37  const executedCalls = new Set(
38    interaction.steps
39      .filter((s) => s.type === "function_result")
40      .map((s) => s.call_id)
41  );
42
43  const pendingCalls = interaction.steps.filter(
44    (s) => s.type === "function_call" && !executedCalls.has(s.id)
45  );
46
47  for (const call of pendingCalls) {
48    console.log(`正在执行客户端工具：${call.name} (ID：${call.id})`);
49    // 执行你的本地 API/数据库查询，并在第二轮交互中将 function_result 发送回去
50  }
51}

网络凭据刷新

访问令牌和短期 API 密钥会过期。你可以在下一次交互时，通过传递现有的 environment_id 和新的网络配置来刷新凭据或轮换密钥。新规则会立即替换旧规则。你的沙箱会保持其文件系统状态、已安装的包和已克隆的仓库不变。

typescript

1import { GoogleGenAI } from "@google/genai";
2const client = new GoogleGenAI({});
3
4// 1. 第一次交互：使用初始令牌
5const first = await client.interactions.create({
6  agent: "antigravity-preview-05-2026",
7  input: "使用 GCS JSON API 列出 gs://my-bucket/reports/ 中的文件。",
8  environment: {
9    type: "remote",
10    network: {
11      allowlist: [
12        {
13          domain: "storage.googleapis.com",
14          transform: {
15            Authorization: "Bearer INITIAL_TOKEN",
16          },
17        },
18      ],
19    },
20  },
21});
22
23// 2. 稍后：在同一个环境中刷新令牌
24const result = await client.interactions.create({
25  agent: "antigravity-preview-05-2026",
26  input: "现在从同一个存储桶下载文件 reports/q1.csv。",
27  environment: {
28    type: "remote",
29    environment_id: first.environment_id,
30    network: {
31      allowlist: [
32        {
33          domain: "storage.googleapis.com",
34          transform: {
35            Authorization: "Bearer REFRESHED_TOKEN",
36          },
37        },
38      ],
39    },
40  },
41});
42console.log(result.output_text);