Gemini API Managed Agents：背景任務與遠端 MCP

今天我們宣布 Gemini API 中的 Managed Agents 新增多項功能，包括背景執行、遠端 MCP 伺服器整合、自訂函式呼叫以及跨互動更新憑證。這些更新直接回應了開發者的回饋與產品需求，讓你能夠建構可靠、可投入生產環境的 Agent。

透過 Gemini Interactions API 中的 Managed Agents，你只需呼叫單一端點，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，客戶端應用程式可用來輪詢狀態、串流進度，或稍後重新連線，讓 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: "Clone 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。現在，你可以直接將 Managed Agents 連接到遠端 Model Context Protocol (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);