Hooks в Managed Agents Gemini API: контроль действий и лимит токенов

Hooks в Managed Agents Gemini API запускают проверку прямо перед или сразу после действия агента внутри удалённой Linux-среды. Обработчик pre_tool_execution может отклонить опасный вызов, а post_tool_execution — запустить линтер, тест или аудит уже выполненной операции.

По состоянию на 28 июля 2026 года это полезный эксплуатационный предохранитель, но не строгая граница безопасности. Hooks работают только со встроенными инструментами контейнера, не охватывают custom functions и внешние MCP-серверы, а при ошибке или таймауте разрешают выполнение. Сами Managed Agents всё ещё находятся в Public Preview.

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

Что hooks действительно контролируют

Конфигурация хранится в .agents/hooks.json или /.agents/hooks.json. Для каждого правила задаются событие, регулярное выражение matcher и один или несколько обработчиков. Они выполняются последовательно.

{
  "security-gate": {
    "pre_tool_execution": [{
      "matcher": "code_execution|write_file",
      "hooks": [{
        "type": "command",
        "command": "python3 /.agents/hooks-scripts/gate.py",
        "timeout": 10
      }]
    }]
  },
  "audit": {
    "post_tool_execution": [{
      "matcher": ".*",
      "hooks": [{
        "type": "http",
        "url": "https://audit.example.com/agent-events",
        "timeout": 10
      }]
    }]
  }
}

В этом примере первый скрипт получает сведения о вызове code_execution или write_file. Ответ {"decision":"deny","reason":"..."} отменяет действие и возвращает причину модели. Второй обработчик отправляет сведения о завершённых операциях во внешнюю систему аудита. Домен для HTTP-hook нужно заранее добавить в сетевой список разрешений.

Где заканчивается защита hooks

Главное ограничение — охват. Hooks видят code_execution и файловые операции read_file, write_file, list_files и delete_file. Вызовы пользовательских функций и внешних MCP-инструментов обрабатываются за пределами контейнера, поэтому эти события не проходят через hooks.json.

Второе ограничение опаснее: Google выбрала режим fail-open. Если скрипт завершается с ошибкой, HTTP-сервис отвечает не кодом 2xx, истекает таймаут или обработчик возвращает неверный JSON, действие разрешается. Такой выбор не даёт сломанному линтеру остановить приложение, но исключает использование hook как единственного обязательного шлюза.

Есть и риск подмены конфигурации. Агент с правом записи в рабочую область или доступом к shell может изменить локальный .agents/hooks.json и связанные скрипты. Для защиты от недоверенного выполнения Google рекомендует подключать конфигурацию из репозитория только для чтения. Секреты для HTTP-hook лучше не хранить в JSON: исходящий прокси умеет подставлять заголовки авторизации по правилам network.allowlist.transform.

Практический вывод совпадает с тем, как крупные платформы защищают другую автоматизацию. GitHub в своём обзоре атак на цепочку поставок перечисляет несколько независимых барьеров: 72-часовой режим только для чтения после чувствительных изменений npm-аккаунта, безопасное поведение actions/checkout, политики запуска workflows и кэш только для чтения у недоверенных триггеров. Один hook не заменяет такую эшелонированную схему.

Лимит токенов, новая модель и запуски по расписанию

Hooks вышли вместе с бюджетными и операционными настройками. Это важное дополнение: по документации Google один запуск Managed Agent обычно потребляет от 100 тысяч до 3 миллионов токенов из-за повторяющихся циклов рассуждения и инструментов. Мы уже разбирали, почему лимиты важны для защиты от лишних вызовов инструментов.

max_total_tokens — best-effort ограничение, а не точный финансовый рубильник. Если агент остановился со статусом incomplete, состояние и контекст сохраняются. Продолжить работу можно новым вызовом с previous_interaction_id, идентификатором среды и свежим бюджетом.

Как встроить hooks в безопасный процесс

1. Закрепите модель и задайте max_total_tokens. Так изменение модели по умолчанию не поменяет поведение незаметно, а длинный цикл получит верхнюю границу расхода.
2. Используйте pre_tool_execution для запрета разрушительных команд и доступа к закрытым каталогам. Обязательные политики доступа держите вне writable-среды, потому что hook может сломаться или быть изменён.
3. После записи файлов запускайте тесты, линтеры и аудит через post_tool_execution. Отдельный контроль нужен для custom functions и MCP-инструментов.
4. Ограничьте исходящую сеть, выдавайте короткоживущие учётные данные с минимальными правами и оставьте человеческое подтверждение перед развёртыванием или изменением данных.

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

Короткие ответы

Перехватывают ли hooks MCP и custom functions?

Нет. Hooks в Managed Agents Gemini API срабатывают только для встроенных инструментов контейнера: выполнения кода и операций с файлами. Внешние mcp_server и пользовательские function обрабатываются вне этого контура.

Что произойдёт при ошибке hook?

Вызов будет разрешён. Ошибка скрипта, таймаут, HTTP-ответ не 2xx или неверный JSON переводят обработчик в режим allow. Для обязательного запрета нужен дополнительный контроль вне sandbox.

Может ли post-tool hook отменить действие?

Нет. post_tool_execution запускается после операции и подходит для тестов, форматирования и телеметрии. Значение decision в его ответе игнорируется.

Managed Agents уже готовы для продакшена?

Google использует формулировку production-ready в анонсе, но официальная документация сохраняет статус Public Preview и требует проверять действия и результаты перед чувствительными операциями. Gemini 3.6 Flash доступна в GA, однако это не меняет статус самого агентного сервиса.

Источники и что читать дальше

Факты проверены 28 июля 2026 года. Технические характеристики взяты из официальной документации; маркетинговые оценки Google не представлены как независимые результаты.

• Google: анонс обновления Managed Agents
• Google AI for Developers: Hooks
• Google AI for Developers: Agents Overview
• Google AI for Developers: Antigravity Agent
• Google AI for Developers: Gemini Triggers API
• OpenAI: отчёт об агентной разработке научного ПО
• GitHub: защита npm и GitHub Actions от атак на цепочку поставок

Читайте также

• ИИ-агенты: что это и когда они действительно нужны
• Gemini API Managed Agents: фоновые задачи и MCP
• ИИ-агенты в продакшене: tokenmaxxing и tool-overuse