Managed Agents в Gemini API: как запускать фоновые задачи и безопасно подключать MCP

7 июля 2026 года Google расширила Managed Agents в Gemini API. Управляемые AI-агенты получили фоновое выполнение длительных задач, прямое подключение remote MCP-серверов, пользовательские функции рядом со встроенными инструментами и обновление учётных данных без пересоздания рабочей среды.

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

Ниже разберём, как устроены Managed Agents, где проходит граница ответственности Google и разработчика и какую минимальную защиту стоит заложить до первого рабочего прототипа.

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

Managed Agents (управляемые агенты) — это размещённая Google агентная среда поверх Gemini Interactions API. Один вызов API может создать изолированную Linux-песочницу, в которой агент планирует действия, запускает Python, Node.js и команды оболочки, работает с файлами и обращается к веб-ресурсам.

Стандартная языковая модель возвращает ответ. Управляемый агент выполняет цикл: ставит подзадачу, выбирает инструмент, наблюдает результат и продолжает работу, пока не достигнет цели или не столкнётся с ошибкой. Разработчику не нужно отдельно собирать контейнер и программировать базовый цикл оркестрации.

Среда и история разговора при этом разделены:

• environment_id указывает на песочницу с файлами и установленными пакетами;

• previous_interaction_id продолжает контекст предыдущего взаимодействия;

• новый запрос может использовать оба идентификатора или только один из них.

Это важное различие. Иногда агенту нужны прежние файлы, но не нужен длинный диалог. В другом сценарии требуется продолжить рассуждение в новой чистой среде.

Сервис пока находится в статусе Public Preview (публичная предварительная версия). Google прямо рекомендует проверять действия и результаты агента перед использованием в чувствительных процессах.

Что изменилось в июльском обновлении

Фоновые задачи без открытого соединения

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

Это удобно для заданий, которые естественно живут в очереди:

• анализ проекта и запуск тестов;

• сбор данных из нескольких источников;

• подготовка ежедневного дайджеста;

• построение отчёта или набора файлов;

• обработка задачи, запущенной из административной панели.

Фоновое выполнение требует сохранения взаимодействия (store: true), которое включено по умолчанию. Активную задачу можно отменить отдельным вызовом API.

Прямое подключение remote MCP

MCP, или Model Context Protocol (протокол подключения моделей к инструментам и данным), позволяет описать доступные агенту операции единообразным способом. В Managed Agents удалённый HTTP MCP-сервер теперь можно зарегистрировать как инструмент типа mcp_server.

Практический результат: агент может обратиться к вашему каталогу товаров, базе знаний, CRM или внутреннему API без самописного прокси только ради преобразования вызовов инструментов. Но сам факт прямого подключения не делает интеграцию безопасной. MCP-сервер должен проверять авторизацию, валидировать параметры и ограничивать каждую операцию на своей стороне.

Пользовательские функции вместе с песочницей

Custom function calling (вызов пользовательских функций) нужен, когда бизнес-логику следует выполнять в вашем приложении, а не в удалённой среде Google. Агент формирует запрос функции и переводит взаимодействие в состояние requires_action. Клиент проверяет аргументы, выполняет локальный код и отправляет результат вторым запросом.

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

Обновление токенов без потери файлов

Короткоживущие OAuth-токены могут истечь во время длинного процесса. Теперь на следующем взаимодействии можно передать прежний environment_id и новую конфигурацию сети. Правила доступа заменятся, но файлы, репозитории и установленные пакеты в песочнице сохранятся.

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

Безопасный минимальный пример на JavaScript

Ниже — базовый запуск фоновой задачи через официальный пакет @google/genai. Пример намеренно не подключает секреты и ограничивает исходящий трафик двумя доменами. Агент получает только инструменты поиска и чтения URL, поэтому не может вызвать произвольную пользовательскую функцию или MCP-сервер.

Перед запуском создайте резервную копию данных, если адаптируете пример для рабочего проекта. Установите пакет и задайте ключ через переменную окружения, а не в исходном коде:

npm install @google/genai

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

const client = new GoogleGenAI({});

async function waitForInteraction(interactionId) {
  let result = await client.interactions.get(interactionId);

  while (result.status === "in_progress") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    result = await client.interactions.get(interactionId);
  }

  if (result.status !== "completed") {
    throw new Error(`Agent finished with status: ${result.status}`);
  }

  return result;
}

async function main() {
  const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: [
      {
        type: "text",
        text: [
          "Изучи официальную документацию Gemini API по Managed Agents.",
          "Подготовь краткий отчёт о background execution и remote MCP.",
          "Не выполняй внешние действия и не изменяй данные.",
        ].join(" "),
      },
    ],
    environment: {
      type: "remote",
      network: {
        allowlist: [
          { domain: "ai.google.dev" },
          { domain: "blog.google" },
        ],
      },
    },
    tools: [
      { type: "google_search" },
      { type: "url_context" },
    ],
    background: true,
  });

  console.log(`Started: ${interaction.id}`);
  const result = await waitForInteraction(interaction.id);
  console.log(result.output_text);
}

main().catch((error) => {
  console.error(error instanceof Error ? error.message : error);
  process.exitCode = 1;
});

Модель агента в примере имеет preview-идентификатор. Перед внедрением нужно сверить актуальное имя в документации: предварительные модели и параметры могут меняться.

Как подключать MCP без лишних полномочий

Удалённый MCP-сервер добавляется в массив tools. Минимальная конфигурация выглядит так:

tools: [
  {
    type: "mcp_server",
    name: "catalog",
    url: "https://mcp.example.com/server",
  },
]

Для рабочего проекта одной этой записи недостаточно. Безопасная схема включает несколько уровней:

1. Агент получает отдельную сервисную учётную запись, а не права администратора.

2. MCP-сервер разрешает только необходимые методы. Если агенту нужен поиск, ему не нужны удаление и публикация.

3. Все аргументы проверяются обычным детерминированным кодом до обращения к базе или внешнему API.

4. Операции записи требуют идемпотентного ключа и, для критичных действий, подтверждения человеком.

5. В журнал попадают идентификатор взаимодействия, вызванный инструмент, параметры без секретов, результат и пользователь-инициатор.

6. Исходящая сеть песочницы ограничивается allowlist (списком разрешённых доменов).

У сред Managed Agents по умолчанию открыт исходящий доступ в интернет. Поэтому настройка allowlist — не дополнительное усиление, а разумная исходная конфигурация. Не добавляйте правило domain: "*", если оно не нужно конкретной задаче.

Исследование Agent Data Injection Attacks, опубликованное в июле 2026 года, показывает ещё одну проблему: вредоносные данные могут маскироваться под доверенные метаданные или ответы инструментов. Авторы продемонстрировали атаки на реальные браузерные и кодовые агенты. Песочница снижает последствия, но не отделяет автоматически доверенные входы от недоверенных. Внешний текст, issue, веб-страница и ответ MCP должны считаться недоверенными до проверки.

Где Managed Agents действительно полезны

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

Менее удачный первый сценарий — дать агенту постоянный доступ на запись в CRM, интернет-магазин или production-сервер. Если задача сразу требует максимальных прав и не предусматривает проверку результата, управляемая песочница не исправит слабую архитектуру разрешений.

Managed Agents также не всегда выгоднее обычного вызова модели. Для короткого извлечения данных, классификации или генерации текста агентный цикл добавляет стоимость и задержку. По документации Google, одно взаимодействие может включать много циклов рассуждения и потреблять от 100 тысяч до 3 миллионов токенов. Для простой операции лучше оставить детерминированный код и один модельный запрос.

Ограничения, которые важно учитывать

Сервис находится в Public Preview, поэтому интерфейсы и модель агента могут измениться. Среда хранится семь дней после последней активности, а затем удаляется. После простоя виртуальная машина останавливается, и следующий запрос может начаться с холодного запуска.

Есть и организационные ограничения:

• результат агента нельзя считать правильным только потому, что задача получила статус completed;

• стоимость определяется не одним ответом модели, а всей цепочкой действий и рассуждений;

• секреты следует передавать через сетевые преобразования заголовков, а не записывать в файлы песочницы;

• права внешних сервисов должны ограничиваться независимо от настроек агента;

• операции записи требуют журналирования, защиты от повторов и понятного сценария отката.

Если команда только начинает работать с агентами, полезно сначала сформулировать границы их полномочий. Об этом подробнее рассказано в материале «AI-агенты выходят из IDE в бизнес-процессы: кто их контролирует». Для проектных инструкций пригодится шпаргалка по структуре проекта для Claude Code, а общие принципы надёжной агентной среды разобраны в статье про OpenClaw и AI-инфраструктуру.

Чек-лист перед первым прототипом

• Выберите задачу, результат которой можно проверить до применения.

• Ограничьте исходящую сеть конкретными доменами.

• Выдайте MCP и пользовательским функциям минимальные права.

• Разделите чтение, подготовку изменений и применение изменений.

• Не помещайте API-ключи и токены в промпт, исходный код или файлы агента.

• Добавьте тайм-аут, отмену задачи и обработку статусов ошибки.

• Сохраняйте журнал вызовов инструментов без секретов.

• Установите лимит расходов и наблюдайте за фактическим потреблением.

• Проверяйте актуальную версию SDK и идентификатор preview-модели.

• Проведите тест с вредоносным содержимым во внешнем источнике.

Вывод

Июльское обновление делает Gemini Managed Agents заметно ближе к рабочей инфраструктуре. Фоновые задания убирают зависимость от долгого HTTP-соединения, remote MCP упрощает подключение инструментов, а обновление короткоживущих токенов позволяет не жертвовать состоянием среды ради безопасности.

Но управляемый агент не означает управляемый риск. Google обслуживает песочницу и агентный цикл, а разработчик по-прежнему отвечает за права внешних систем, проверку входных данных, подтверждение опасных действий и контроль стоимости. Лучший первый проект — тот, где агент готовит проверяемый артефакт, а не самостоятельно меняет критичные данные.