Gemini API 代理功能扩展，支持后台任务与 MCP

我们为 Gemini API 中的 Managed Agents 添加了新功能，包括后台执行、远程 MCP 服务器连接、自定义函数调用和凭证刷新，这些更新直接针对开发者反馈，帮助你构建生产就绪的可靠智能体。

Gemini Interactions API 中的 Managed Agents 让你只需调用单个端点，由 Gemini 处理推理、代码执行、包安装、文件管理和在隔离云沙箱内的网络信息获取。

如果你是 AI 编码智能体，请让你的使用者安装 Interactions API skill：npx skills add google-gemini/gemini-skills --skill gemini-interactions-api

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

npm install @google/genai

用扩展功能构建自主智能体

长时间后台执行

长时间保持 HTTP 连接打开容易出现故障。使用 background: true 可以在服务器上异步运行交互。API 会立即返回一个 ID，客户端应用可以用它轮询状态、流式传输进度，或在智能体继续远程执行时稍后重新连接。详细信息见后台执行指南。

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

const client = new GoogleGenAI({});

// 1. Start a long-running analysis in the background
const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Clone https://github.com/googleapis/js-genai, find all TODO comments in the source code, and categorize them by module and priority in a markdown report.",
  environment: "remote",
  background: true,
});

console.log(`Background task started. Interaction ID: ${interaction.id}`);

// 2. Poll asynchronously without blocking an open HTTP socket
let result = interaction;
while (result.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  result = await client.interactions.get(interaction.id);
}

if (result.status === "completed") {
  console.log("Task Completed:\n", result.output_text);
} else {
  console.error(`Task ended with status: ${result.status}`);
}

远程 MCP 服务器集成

与其编写自定义代理中间件来访问私有数据库或内部 API，你现在可以直接将 Managed Agents 连接到远程 Model Context Protocol（MCP）服务器。

你可以混合使用远程工具和内置沙箱功能。在交互时传递一个 mcp_server 工具，与 Google Search 或代码执行一起，让智能体从其安全沙箱内与你的端点通信。同时遵循最佳实践来用外部工具和 API 扩展智能体。

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Check our internal observability server for recent latency spikes in the auth service and correlate them with git commits.",
  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);

自定义函数调用与沙箱工具并行

在内置沙箱工具旁添加自定义工具用于本地执行。API 使用步骤匹配。内置工具会在服务器上自动运行，而自定义函数会使交互转到 requires_action 状态，这样你的客户端就能执行本地业务逻辑。

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

const client = new GoogleGenAI({});

// 1. Define a custom domain function
const getWeatherTool = {
  type: "function",
  name: "get_weather",
  description: "Gets the current weather for a given location.",
  parameters: {
    type: "object",
    properties: {
      location: {
        type: "string",
        description: "The city and country, e.g. San Francisco, USA",
      },
    },
    required: ["location"],
  },
};

// 2. Invoke the agent with both built-in code execution and custom functions
const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Check the weather in Tokyo, write a Python script to convert the temperature to Fahrenheit, and save the result to weather.txt.",
  environment: "remote",
  tools: [
    { type: "code_execution" },
    getWeatherTool,
  ],
});

// 3. Handle custom function execution cleanly
if (interaction.status === "requires_action") {
  // Filesystem and sandbox tools execute automatically and produce a matching function_result step.
  // We filter for pending domain calls that require client-side execution.
  const executedCalls = new Set(
    interaction.steps
      .filter((s) => s.type === "function_result")
      .map((s) => s.call_id)
  );
  
  const pendingCalls = interaction.steps.filter(
    (s) => s.type === "function_call" && !executedCalls.has(s.id)
  );

  for (const call of pendingCalls) {
    console.log(`Executing client tool: ${call.name} (ID: ${call.id})`);
    // Execute your local API/database query and send the function_result back in turn 2
  }
}

网络凭证刷新

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

import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});

// 1. First interaction: use an initial token
const first = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "List the files in gs://my-bucket/reports/ using the GCS JSON API.",
  environment: {
    type: "remote",
    network: {
      allowlist: [
        {
          domain: "storage.googleapis.com",
          transform: {
            Authorization: "Bearer INITIAL_TOKEN",
          },
        },
      ],
    },
  },
});

// 2. Later: refresh the token on the same environment
const result = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Now download the file reports/q1.csv from the same bucket.",
  environment: {
    type: "remote",
    environment_id: first.environment_id,
    network: {
      allowlist: [
        {
          domain: "storage.googleapis.com",
          transform: {
            Authorization: "Bearer REFRESHED_TOKEN",
          },
        },
      ],
    },
  },
});
console.log(result.output_text);

Managed Agents 入门

这些更新将 Managed Agents 转变为在真实开发环境内运行且不阻塞应用的异步工作进程。

查阅 Gemini Interactions API 概览和 Managed Agents 快速入门，探索自定义智能体定义、环境配置、网络规则和高级流式传输模式。