Держать HTTP-соединение открытым 20 минут, пока агент клонирует репозиторий, анализирует код и пишет отчёт. Это мазохизм. Любая сетевая ошибка, таймаут прокси, перезагрузка клиента, и вся работа потеряна. Google это понял и добавил в Managed Agents то, что разработчики просили месяцами: асинхронное выполнение, прямую интеграцию с MCP-серверами и возможность обновлять credentials на лету.

Что такое Managed Agents в Gemini API

Managed Agents, это режим Interactions API, где Gemini сам берётся за reasoning, выполнение кода, установку пакетов, работу с файлами и поиск в вебе внутри изолированного cloud sandbox. Вы вызываете один эндпоинт, передаёте задачу, API сам решает, какие инструменты использовать и в каком порядке. Не нужно писать orchestrator, управлять Docker-контейнерами или парсить выводы модели. Всё происходит в управляемой среде Google.

До недавнего обновления это работало только синхронно: клиент держит соединение, ждёт результат, получает ответ. Для простых задач, таких как перевод текста или ответ на вопрос, это нормально. Для сложных, таких как анализ кодовой базы, сбор данных из нескольких API или генерация отчёта с визуализациями, это архитектурная ловушка.

Background execution: агент работает, пока вы занимаетесь делами

Проблема синхронного режима очевидна: long-running задачи блокируют клиент. Если агенту нужно 15 минут, чтобы пройтись по 50 файлам, найти TODO-комментарии, категоризировать их по модулям и приоритетам, а потом оформить в markdown-отчёт, ваше приложение висит 15 минут. Любой обрыв связи, timeout на load balancer, restart процесса, и вы теряете не только текущую задачу, но и весь прогресс.

Решение: параметр background: true. API мгновенно возвращает ID взаимодействия, а агент продолжает работать на сервере. Клиент может поллить статус, стримить прогресс или вообще отключиться и вернуться позже.

const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Clone https://github.com/googleapis/js-genai, find all TODO comments, categorize by module and priority",
  environment: "remote",
  background: true
});

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

// Poll asynchronously
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:", result.output_text);
}

Агенты превращаются из синхронных функций в асинхронные workers, которые живут в облаке и не зависят от жизнеспособности клиента. Мобильное приложение запускает задачу, уходит в фон, возвращается через час и получает результат. CLI-утилита запускает пакетный анализ, выходит, потом собирает результаты. Web-приложение обрабатывает тысячи параллельных задач без тысяч открытых соединений.

Remote MCP: прямое подключение к вашим инструментам

Агентам нужен доступ к внутренним системам. observability-сервер, внутренняя база данных, корпоративный API. Всё это закрыто от публичного интернета. Раньше приходилось писать прокси-микросервис, который торчал наружу, принимал запросы от агента, ходил во внутреннюю сеть, возвращал результат. Это дополнительная инфраструктура, дополнительные точки отказа, дополнительные проблемы с безопасностью.

Теперь можно подключить managed agent напрямую к remote Model Context Protocol (MCP) серверу. MCP, это открытый протокол от Anthropic для стандартизированного взаимодействия с инструментами. Если у вас есть MCP-сервер, который оборачивает вашу внутреннюю telemetry-систему, агент может вызывать его напрямую из sandbox.

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

Можно миксовать remote MCP с встроенными инструментами. Агент одновременно использует Google Search для публичной информации, code execution для анализа данных и ваш MCP-сервер для доступа к внутренним системам. Всё происходит в изолированном sandbox, но с контролируемым доступом к вашим эндпоинтам.

Для enterprise-сценариев это удобно. Агент анализирует инцидент: ищет в документации через Google Search, пишет скрипт для парсинга логов через code execution, дёргает вашу Prometheus-систему через MCP, correlates с последними деплоями через GitLab API через ещё один MCP. Всё в одной задаче, без необходимости писать orchestrator.

Custom function calling: гибридный подход

Что если часть логики должна выполняться локально? У вас есть legacy API, который нельзя вынести в MCP-сервер, или бизнес-логика, которая должна работать на вашей инфраструктуре по compliance-причинам. Для этого существует custom function calling alongside sandbox tools.

API использует step matching: встроенные инструменты (code execution, Google Search) выполняются автоматически на сервере, а custom functions переводят взаимодействие в статус requires_action, чтобы клиент мог выполнить свою логику и вернуть результат.

const getWeatherTool = {
  type: "function",
  name: "get_weather",
  description: "Gets current weather for a location",
  parameters: {
    type: "object",
    properties: {
      location: {
        type: "string",
        description: "City and country, e.g. San Francisco, USA"
      }
    },
    required: ["location"]
  }
};

const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Check weather in Tokyo, convert to Fahrenheit, save to weather.txt",
  environment: "remote",
  tools: [
    { type: "code_execution" },
    getWeatherTool
  ]
});

if (interaction.status === "requires_action") {
  // Filesystem tools executed automatically
  // Filter for pending custom function calls
  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}`);
    // Execute your local API call and send result back
  }
}

Получается гибридная архитектура: тяжёлая часть (анализ, генерация кода, поиск) происходит в облаке, а domain-specific логика (проверка прав доступа, валидация бизнес-правил, запись в локальную БД) остаётся под вашим контролем. Агент не пытается угадать, что вам нужно. Он явно делегирует вам задачи, которые выходят за пределы его sandbox.

Credential refresh: токены истекают, state остаётся

Четвёртое обновление решает проблему, о которой редко думают до production: access tokens expire. OAuth-токены живут час, short-lived API keys живут минуты. Если агент работает над задачей 30 минут и ему нужно обратиться к внешнему API в конце, токен, с которым он начинал, уже мёртв.

Раньше единственный вариант был пересоздавать environment с новыми credentials. Но environment, это не просто настройки сети. Это файловая система, установленные пакеты, клонированные репозитории, промежуточные результаты. Пересоздание означает потерю всего прогресса.

Теперь можно refresh credentials, передав существующий environment_id с новой network configuration:

// First interaction with initial token
const first = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "List files in gs://my-bucket/reports/",
  environment: {
    type: "remote",
    network: {
      allowedEndpoints: [
        { domain: "storage.googleapis.com", rules: { Authorization: "Bearer INITIAL_TOKEN" } }
      ]
    }
  }
});

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

Новые правила заменяют старые немедленно. Sandbox сохраняет файловую систему, установленные пакеты, клонированные репозитории. Агент продолжает работу со свежими credentials, как будто ничего не произошло.

Для long-running workflows это необходимо. Агент собирает данные из нескольких источников: начинает с одним токеном, через 10 минут refresh'ит его, через 20 минут ещё раз. Или сценарий, где разные этапы задачи требуют разных credentials (read-only для анализа, write для сохранения результатов). Всё это теперь возможно без пересоздания environment.

Часто задаваемые вопросы

Чем Managed Agents отличаются от обычного function calling?

Function calling, это низкоуровневый механизм: модель возвращает список вызовов функций, клиент их выполняет, возвращает результаты, модель решает, что делать дальше. Вы пишете orchestrator, управляете состоянием, обрабатываете ошибки. Managed Agents, это высокоуровневая абстракция: вы передаёте задачу на естественном языке, а API сам решает, какие инструменты использовать, как обрабатывать ошибки, когда запросить дополнительную информацию. Вы не пишете цикл reasoning. Gemini делает это за вас.

Можно ли использовать Managed Agents для production-нагрузок?

API находится в preview (antigravity-preview-05-2026), но designed для production. Sandbox изолирован, credentials ограничены allowedEndpoints, state сохраняется между взаимодействиями через environment_id. Однако preview-статус означает, что API может измениться, SLA не гарантирован, а pricing может отличаться от финальной версии. Для production стоит начать с non-critical workflows, мониторить costs и иметь fallback на ручную обработку.

Как обеспечивается безопасность sandbox?

Каждый агент работает в изолированной среде с контролируемыми сетевыми правилами. Вы явно указываете, к каким доменам можно обращаться (allowedEndpoints), какие credentials передавать. Sandbox не имеет доступа к вашему VPC по умолчанию. Только к эндпоинтам, которые вы разрешили. Filesystem изолирован между environment, пакеты устанавливаются в изолированное окружение. Это не Docker-контейнер на вашем сервере. Это управляемая среда Google с явным контролем доступа.

Архитектурные паттерны: когда что использовать

Четыре новых возможности дополняют друг друга. Правильная комбинация зависит от характера задачи.

Для batch-анализа (аудит кодовой базы, генерация отчётов, миграция данных) подходит background execution. Задача запускается, клиент отключается, результат забирается через webhook или polling. Никаких открытых соединений, никаких таймаутов.

Для работы с внутренними системами (observability, CRM, документация) подходит remote MCP. Агент получает прямой доступ к вашим эндпоинтам из sandbox без необходимости поднимать прокси-слой. Если у вас уже есть MCP-серверы для IDE, переиспользуйте их.

Для задач, где часть логики требует локального контекста (проверка прав, валидация по внутренним правилам, запись в локальную БД), подходит custom function calling. Агент работает в облаке, но делегирует вам критичные операции. Это hybrid-подход: облачная мощь для reasoning плюс локальный контроль для compliance.

Для long-running workflows с внешними API подходит credential refresh. Агент начинает задачу с одним токеном, обновляет его на лету, продолжает без пересоздания sandbox. Это хорошо для сценариев, где данные собираются из нескольких источников с разными lifecycles credentials.

На практике большинство enterprise-задач комбинируют несколько паттернов. Агент для incident response использует background execution (задача может идти час), remote MCP (доступ к Prometheus и Grafana), custom function calling (проверка on-call расписания через локальный API) и credential refresh (токены к облачным провайдерам обновляются каждые 30 минут).

Итог

Обновление Managed Agents превращает их из эксперимента в рабочий инструмент. Background execution решает проблему long-running workflows, remote MCP убирает необходимость в прокси-инфраструктуре, custom function calling даёт контроль над domain-specific логикой, credential refresh позволяет работать с истекающими токенами без потери state.

Если вы строите AI-агентов для enterprise-сценариев (анализ кодовых баз, автоматизация incident response, сбор данных из внутренних систем), Managed Agents стоит попробовать. Начните с простого сценария (анализ TODO в репозитории), добавьте MCP-сервер для доступа к вашей telemetry, поэкспериментируйте с background execution. Это займёт час, но даст понимание, насколько этот подход подходит для ваших задач.

Документация доступна в Gemini Interactions API overview и managed agents quickstart. JavaScript SDK — @google/genai, Python и cURL тоже поддерживаются.