Как использовать Google AX? Руководство по установке, развёртыванию и разработке

В официальном репозитории Google AX описаны runner, манифесты задач, сетевые настройки и sandbox — четыре аспекта исполнения, которые важно проверить до развёртывания (репозиторий Google AX).

Симптом: пример запускается локально, но непонятно, можно ли безопасно поручить AX реальные задачи.
Быстрый путь: сначала пройдите официальный Quickstart на одной задаче, затем проверьте жизненный цикл рабочей области, доступ к сети и видимость ошибок. Google AX помогает организовать Agent-задачи и их исполнение; он не заменяет модель или готовое прикладное приложение.

Эта инструкция для Go-разработчиков, которым нужно подключить собственный Agent к runner; для SRE и платформенных инженеров, проверяющих границы исполнения и наблюдаемость; для технических руководителей, выбирающих локальную или удалённую среду для пробного развёртывания.

Последняя проверка: 25 сентября 2026 года. Сверено с текущими на эту дату репозиторием Google AX и его Quickstart, а также документацией runner, манифестов, сети и sandbox.

Google AX в цепочке Agent-задачи

Google AX — среда выполнения и организации задач: она задаёт способ передать работу, подготовить для неё рабочую область, запустить исполнение через runner и наблюдать за происходящим. Это не сама модель и не универсальный Agent, который автоматически выбирает бизнес-процессы за вас. В понятиях AX отдельно существуют задача, рабочая область и средство исполнения; назначение этих сущностей раскрыто в официальном описании концепций.

Для решения о внедрении полезно разделить ответственность:

• Ваша программа Agent определяет, что считать задачей, как интерпретировать входные данные и когда работа завершена.
• Google AX предоставляет структуру исполнения, в которой можно передавать задачу и рабочую область, а затем запускать её через runner.
• Модель и внешние сервисы обеспечивают те возможности, которые вы подключили в собственной программе. Их доступность, учётные данные и ограничения не следует автоматически приписывать AX.
• Среда развёртывания задаёт реальные границы безопасности: права процесса, доступные файлы, исходящий трафик, хранение журналов и возможность очистить рабочую область.

Из этого следует важная оговорка: наличие в документации отдельного раздела о sandbox не означает, что любой способ запуска автоматически изолирован настолько, насколько требует ваша политика. Нужно выяснить, какую часть предоставляет выбранный runner, что включается его конфигурацией, а что обязана ограничить ваша инфраструктура.

В качестве примера: если Agent читает исходники и предлагает патч, задача должна работать в определённой рабочей области, а не получать неограниченный доступ к домашнему каталогу разработчика. Если же Agent обращается к внутреннему API, изоляция файлов сама по себе не ограничивает сетевые запросы. Эти две границы проверяются отдельно.

Подготовка среды к установке Google AX

Начните не с выбора серверного размера, а с проверки документации именно того состояния репозитория, которое собираетесь использовать. Требования к Go, команды запуска и состав зависимостей могут измениться; поэтому здесь не стоит фиксировать версию инструментария или ресурсы без подтверждения актуальным источником. Сверьте их с README и Quickstart в официальном репозитории.

Для первого прохода подготовьте рабочую копию репозитория, среду Go, доступ к указанным в Quickstart зависимостям и отдельную тестовую область файловой системы. Не переносите в тест секреты от рабочих систем: сначала выясните, каким процессам и командам они будут доступны.

Удобная начальная последовательность для получения исходников:

git clone https://github.com/google/ax.git
cd ax

Эти команды получают репозиторий и переходят в его каталог. После этого выполняйте команды Quickstart из актуального README без подстановки случайных флагов или устаревших инструкций из сторонних примеров. Перед запуском убедитесь, что текущая ветка, конфигурация и зависимости соответствуют именно той процедуре, которую вы собираетесь проверить.

Перед началом отметьте для себя:

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

Если на любой из этих вопросов пока нет ответа, ограничьте тест безвредной задачей и изолированной рабочей областью. Установка, которая завершается успешно, подтверждает только работоспособность конкретного пути запуска — но не готовность к многопользовательской эксплуатации.

Первый запуск: как выполнить задачу и подготовить рабочую область?

Quickstart стоит проходить как проверку жизненного цикла, а не как копирование одной команды. В официальном примере задачи и описании полей манифеста сверяйте действительные имена элементов и допустимый формат. Не добавляйте поля «по аналогии» с другим фреймворком: интерфейс должен подтверждаться самим репозиторием.

Рабочий проход выглядит так:

1. Выберите безопасную тестовую задачу. Сформулируйте действие с проверяемым результатом: например, проанализировать специально подготовленный файл или выполнить ограниченную команду в тестовом проекте. Не используйте исходники и ключи, к которым задача не должна иметь доступ.
2. Определите вход задачи. Проследите, где в Quickstart он задаётся и как попадает в объект или манифест Task. Зафиксируйте, какие части входа являются инструкцией, а какие — данными. Так проще отличить сбой передачи задачи от ошибки в логике Agent.
3. Укажите рабочую область. Подготовьте каталог для конкретного теста и проверьте, что путь действительно соответствует ожидаемой области. Не предполагайте, что создание рабочей области означает автоматическое ограничение доступа процесса к остальным каталогам.
4. Запустите пример ровно по Quickstart. Используйте документированные команды и зависимости. Если команда в README изменилась, считайте её текущей версией процедуры, а не заменяйте непроверенным вариантом из старой заметки.
5. Наблюдайте за выполнением. Сопоставьте исходную задачу, подготовку рабочей области, запущенную команду и результат. Запишите, где отображается ошибка и доступен ли вывод процесса. Если команда завершилась неуспешно, проверьте, можно ли определить причину без доступа к машине вручную.
6. Уберите состояние теста. Удалите временные файлы, проверьте, не сохранились ли токены или журналы с секретами, и убедитесь, что повторный запуск не использует случайно данные предыдущей задачи.

Так отвечает и на практический вопрос о подготовке рабочего пространства: его нужно рассматривать как отдельный объект жизненного цикла, связанный с конкретной задачей, а не как абстрактное «место, где работает Agent». Уточните, кто создаёт рабочую область, кто выбирает путь, когда она становится доступной и каким способом очищается. Эти ответы должны следовать из документации и поведения вашего запуска, а не из названия функции.

Сценарий для команды разработки. Разработчик просит Agent проверить изменения в тестовом проекте. Платформа передаёт задачу, выделяет рабочую область, затем runner запускает нужную команду. Если вывод сохранился, но каталог не был очищен, следующий запуск может прочитать оставшиеся файлы. Если же процесс видит каталоги вне выделенной области, одно лишь корректное описание Workspace не обеспечивает изоляцию. Именно поэтому после успешного Quickstart нужно проверять права и фактические границы процесса.

Второй этап: как подключить собственный Agent через runner?

В этой архитектуре runner — граница между описанной задачей и фактическим выполнением команд. Документация runner показывает, как AX организует этот путь; сверяйте с ней реальные интерфейсы, типы и доступные точки расширения, прежде чем менять пример (документация runner).

Для интеграции собственного Agent разбирайте путь данных последовательно:

• Контрольная сторона формирует или принимает Task и связывает её с нужной Workspace.
• Исполняющая сторона получает требуемые данные и запускает документированный процесс или команду.
• Наблюдение должно позволить понять, что принято, что запущено и чем завершилось.
• Ваш Agent отвечает за собственную логику, обработку результата и взаимодействие с подключёнными сервисами.

Не считайте, что AX самостоятельно реализует все эти уровни для любого типа Agent. Встраиваемая программа может требовать собственную команду запуска, конфигурацию, передачу входа и обработку выхода. Найдите в документации runner соответствующие интерфейсы, затем проследите их от описания задачи до точки, где запускается процесс. Если намерение системы можно выразить только через неподтверждённые поля или самодельный контракт, сначала проверьте его на небольшом тесте.

Перед адаптацией кода полезно разделить обязанности по владельцам. Кто формирует Task? Кто назначает рабочую область? Кто передаёт переменные окружения? Кто отвечает за завершение процесса и возврат результата? Чем меньше неявных переходов, тем легче расследовать сбой. Особенно внимательно относитесь к учётным данным: если их передают как переменные процесса, выясните, доступны ли они дочерним командам и попадают ли в журналы.

Третий этап: проверка sandbox, сети и наблюдаемости

Проверяйте не наличие слова «изоляция» в описании, а то, что действительно ограничено в вашем способе развёртывания. В документации AX о sandbox и настройках сети отдельно изучите доступные механизмы и их условия. Любое ограничение, которое вы включаете на стороне ОС, контейнера, виртуальной машины или сетевой инфраструктуры, нужно помечать как настройку развёртывания, а не как безусловную возможность AX.

Проверка файловой границы должна включать несколько вопросов. Может ли задача прочитать файл за пределами Workspace? Может ли она изменить его? Как runner задаёт текущий каталог? Что остаётся после завершения? Достаточно ли этих ограничений при ошибке в команде или при запуске недоверенного кода? Одного ответа «файлы вынесены в рабочую папку» недостаточно, если процесс сохраняет права на соседние директории.

Сетевую границу анализируйте независимо от файловой. Установите, куда разрешён исходящий трафик, как ведут себя DNS-запросы и можно ли обратиться к внутренним адресам из тестовой среды. Если задаче не нужен доступ в интернет или к внутренним системам, не предоставляйте его «на будущее». Если доступ нужен, документируйте разрешённые направления и проверяйте результат фактическим запуском, не считая описания конфигурации доказательством её применения.

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

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

Что можно считать встроенным, а что настраивает оператор

Перед пилотом: контрольный список и выбор среды

Прежде чем увеличивать число одновременно выполняемых задач, пройдите проверку по пунктам. Каждый отмеченный пункт должен иметь подтверждение из документации или вашей тестовой среды.

• [ ] Вы выполнили актуальный Quickstart из официального репозитория и сохранили использованные команды.
• [ ] Вы проверили, как вход становится Task и как задаче назначается Workspace.
• [ ] Вы установили, какие каталоги процесс может читать и изменять, а не только указали рабочий путь.
• [ ] Вы проверили сетевую конфигурацию и фактическую доступность внешних и внутренних адресов.
• [ ] Вы выяснили, при каких условиях включаются SSH или другой отладочный доступ и как он отзывается.
• [ ] Вы вызвали контролируемую ошибку и проверили, где увидеть её причину.
• [ ] Вы определили порядок очистки рабочей области и временных учётных данных.
• [ ] Вы назначили владельца журналов, проверили доступ к ним и исключили утечку секретов.
• [ ] Вы описали восстановление после сбоя до того, как увеличивать нагрузку.

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

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

Путь от эксперимента к контролируемому развёртыванию

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

Если после локального теста вам нужен отдельный удалённый контур для проверки Google AX, сравните обязанности команды с возможностями аренды, а не переносите пример напрямую в рабочую среду. Ознакомьтесь с описанием инфраструктуры Kvmjet, используйте справочный центр по удалённой среде для проверки организационных вопросов и сопоставьте пилот с доступным узлом Mac, если такой вариант подходит вашему сценарию.

Самостоятельно обслуживаемый узел может дать больше контроля, но требует времени на обновления, диагностику и восстановление; локальная машина зависит от доступности сотрудника и часто смешивает тест с его рабочей средой. Для короткого пилота аренда Kvmjet может оказаться удобнее именно тем, что позволяет проверить удалённый рабочий процесс без предварительной покупки и постоянного обслуживания собственного устройства. Однако сначала зафиксируйте требования к доступу, очистке и сетевым границам: удалённая среда не заменяет настройку sandbox и проверку runner.