Gemini API عامل‌های مدیریت‌شده را با وظایف پس‌زمینه و MCP از راه دور گسترش داد

امروز ما اعلام می‌کنیم که قابلیت‌های جدیدی برای عامل‌های مدیریت‌شده (Managed Agents) در Gemini API اضافه شده است، شامل اجرا در پس‌زمینه، یکپارچه‌سازی سرور MCP از راه دور، فراخوانی توابع سفارشی و تازه‌سازی اعتبارها در طول تعاملات. این به‌روزرسانی‌ها مستقیماً بر اساس بازخورد توسعه‌دهندگان و نیازهای محصول طراحی شده‌اند تا بتوانید عامل‌های قابل‌اعتماد و آماده‌ی تولید بسازید.

با عامل‌های مدیریت‌شده در Gemini Interactions API، شما یکEndpoint واحد را صدا می‌زنید و Gemini استدلال، اجرای کد، نصب پکیج، مدیریت فایل و اطلاعات وب را در یک سندباکس ابری ایزوله انجام می‌دهد.

اجرا در پس‌زمینه برای تعاملات طولانی‌مدت

حفظ یک اتصال HTTP باز برای وظایف طولانی‌مدت شکننده است. با ارسال background: true، تعاملات به‌صورت ناهمگام روی سرور اجرا می‌شوند. API بلافاصله یک شناسه برمی‌گرداند که برنامه‌های کلاینت می‌توانند از آن برای پرس‌وجوی وضعیت، جریان پیشرفت یا اتصال مجدد استفاده کنند در حالی که عامل به کار خود در راه دور ادامه می‌دهد. برای جزئیات بیشتر راهنمای اجرا در پس‌زمینه را بخوانید.

import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
// ۱. شروع یک تحلیل طولانی‌مدت در پس‌زمینه
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}`);
// ۲. پرس‌وجوی ناهمگام بدون بلاک کردن سوکت HTTP
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های داخلی، اکنون می‌توانید عامل‌های مدیریت‌شده را مستقیماً به سرورهای Model Context Protocol (MCP) از راه دور متصل کنید.

شما می‌توانید ابزارهای از راه دور را با قابلیت‌های داخلی سندباکس ترکیب کنید. یک ابزار mcp_server را در زمان تعامل در کنار google_search یا code_execution ارسال کنید تا عامل از سندباکس امن خود با نقاط پایانی شما ارتباط برقرار کند. و از بهترین شیوه‌ها پیروی کنید وقتی عامل خود را با ابزارها و 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 از تطبیق مرحله‌ای (step matching) استفاده می‌کند. ابزارهای داخلی به‌صورت خودکار روی سرور اجرا می‌شوند، در حالی که توابع سفارشی تعامل را به حالت requires_action می‌برند تا کلاینت منطق تجاری محلی را اجرا کند.

import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
// ۱. تعریف یک تابع حوزه سفارشی
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"],
  },
};
// ۲. فراخوانی عامل با هم‌زمان اجرای کد و توابع سفارشی
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,
  ],
});
// ۳. مدیریت تمیز اجرای تابع سفارشی
if (interaction.status === "requires_action") {
  // ابزارهای فایل‌سیستم و سندباکس به‌صورت خودکار اجرا شده و یک مرحله function_result تولید می‌کنند.
  // ما برای تماس‌های حوزه در انتظار که نیاز به اجرا سمت کلاینت دارند فیلتر می‌کنیم.
  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})`);
    // اجرای کوئری API/پایگاه داده محلی و ارسال function_result در نوبت ۲
  }
}

تازه‌سازی اعتبار شبکه

توکن‌های دسترسی و کلیدهای API کوتاه‌مدت منقضی می‌شوند. شما می‌توانید اعتبارها را تازه کنید یا کلیدها را چرخش دهید با ارسال environment_id موجود به همراه یک پیکربندی شبکه جدید در تعامل بعدی. قوانین جدید بلافاصله جایگزین قوانین قبلی می‌شوند. سندباکس خود حالت فایل‌سیستم، پکیج‌های نصب‌شده و مخازن کلون‌شده را حفظ می‌کند.

import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
// ۱. تعامل اول: استفاده از توکن اولیه
const first = await client.interactions.create({
  agent: "antigravity-preview-05-2026",