Как превратить разовые задачи ИИ-агента в переиспользуемые воркфлоу

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

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

В этой статье показано, как сохранить такой процесс с помощью Swamp. Мы разберём, что становится переиспользуемым, а что нет, соберём небольшой воркфлоу предрелизной проверки и покажем, как один и тот же воркфлоу работает в Claude Code, Cursor, OpenCode и Codex.

Почему удачный прогон агента бесследно исчезает

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

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

Переиспользуемые воркфлоу ИИ-агентов со Swamp: что сохраняется, а что нет

Swamp — это инструмент командной строки, который хранит рабочую автоматизацию агента в виде типизированных моделей, YAML-определений, воркфлоу, версионируемых данных и ссылок на хранилища секретов (vaults) в каталоге .swamp/ внутри Git-репозитория. В README Swamp названы шесть ключевых понятий: модели, описывающие внешние системы как типы; определения — YAML-файлы, которые настраивают одно конкретное применение типа модели; воркфлоу; данные; хранилища секретов; теги.

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

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

Настройка Swamp для вашей агентной среды

Установите бинарный файл официальным скриптом, затем инициализируйте репозиторий для своей агентной среды. Официальный скрипт установки поддерживает macOS и Linux; для Windows также публикуются релизные бинарники.

curl -fsSL https://swamp-club.com/install.sh | sh

swamp repo init                    # Claude Code (default)
swamp repo init --tool cursor      # or: opencode, codex

Claude Code читает скиллы Swamp из .claude/skills/, а инструкции — из CLAUDE.md. Cursor использует .cursor/skills/ и .cursor/rules/swamp.mdc. OpenCode и Codex оба используют .agents/skills/ и AGENTS.md.

Swamp поставляет скиллы внутри своего бинарника и записывает их на диск при запуске init — именно поэтому агент находит их без дополнительной настройки. Автодополнение для оболочки доступно через swamp completions <shell>.

Воркфлоу предрелизной проверки от начала до конца

Воркфлоу Swamp — это YAML-файл, описывающий задания в виде DAG, где каждый шаг вызывает метод определения модели. Как объясняется в разделе How Swamp Works, каждое задание ждёт завершения заданий, от которых зависит, а шаги в одном задании выполняются параллельно, если один не зависит от другого.

Обычно создание определений run-tests, build-artifact и smoke-test поручают агенту. Тем не менее итоговый воркфлоу стоит прочитать, ведь именно этот файл вы утверждаете. Приведённая ниже структура соответствует справочнику по воркфлоу. Плейсхолдеры <method> оставлены намеренно: замените их именами методов, которые действительно предоставляют ваши определения.

id: <keep the generated id>
name: release-check
tags:
  purpose: release
jobs:
  - name: checks
    description: Run tests and build in parallel
    steps:
      - name: tests
        task:
          type: model_method
          modelIdOrName: run-tests
          methodName: <method>
      - name: build
        task:
          type: model_method
          modelIdOrName: build-artifact
          methodName: <method>
  - name: smoke
    dependsOn:
      - job: checks
        condition:
          type: succeeded
    steps:
      - name: smoke
        task:
          type: model_method
          modelIdOrName: smoke-test
          methodName: <method>
version: 1

В этом воркфлоу тесты и сборка выполняются одновременно. Условие condition.type: succeeded удерживает задание smoke, пока оба шага не завершатся успешно. Проверьте файл командой swamp workflow validate release-check, затем запустите его:

swamp workflow run release-check
swamp workflow run release-check --tag env=staging
swamp data query 'attributes.ok == false'   # example query from the Swamp manual

swamp workflow run ожидает завершения прогона (успеха, сбоя или отмены) либо останавливается на шлюзе manual_approval. Успешный прогон завершается с кодом 0, любой другой исход — с ненулевым кодом, поэтому CI может использовать результат как условие прохождения. Флаг --tag переопределяет теги во время выполнения. Каждый прогон сохраняет свои результаты в виде версионируемых данных, которые нельзя изменить задним числом, и их можно снова найти по тегу. Благодаря этому следующая сессия может прочитать, что произошло, а не восстанавливать это по истории чата. Выражение для data query взято из примера в How Swamp Works, и его нужно адаптировать под поля вашей модели.

Успешный смоук-шаг доказывает лишь то, что эндпоинт ответил. Он не доказывает, что страница отрисовалась или что пользователи смогли пройти сценарий до конца. Регрессии фронтенда такого рода становятся заметны при воспроизведении пользовательских сессий на сборке в staging.

Перенос одного воркфлоу между агентными средами

Когда команда переносит воркфлоу Swamp между агентными средами, общими остаются файлы моделей, определений и воркфлоу. Каталог скиллов каждой среды добавлен в gitignore и заполняется самим Swamp, а swamp repo upgrade --tool <name> позволяет разработчику переключиться на другую среду или использовать несколько одновременно. В README отмечено, что каждый инструмент получает собственную папку скиллов, которая не попадает в Git.

Допустим, репозиторий был инициализирован для Claude Code, а коллега работает в Cursor. Агентная среда меняется, но файл воркфлоу остаётся прежним:

# same checkout, teammate on Cursor
swamp repo upgrade --tool cursor
swamp workflow run release-check

Работа swamp workflow run не зависит от того, какой агент её вызвал. Роль агента — писать и редактировать определения, и именно эта часть меняется вместе со средой. OpenCode и Codex используют общие .agents/skills/ и AGENTS.md, поэтому оба инструмента читают скиллы из одного места.

По умолчанию Swamp хранит данные прогонов — данные моделей, прогоны воркфлоу, результаты и журналы аудита — в .swamp/. Командам, которым нужно одинаковое состояние на нескольких машинах, можно переключиться на другой бэкенд хранилища данных, например на общий путь в файловой системе или S3. Рабочая копия переносится вместе с вами: на удалённой машине, настроенной для агентной разработки, тот же воркфлоу запустится, если в этой оболочке доступны учётные данные, необходимые моделям. Чтобы указать Swamp на репозиторий за пределами текущего каталога, используйте --repo-dir или SWAMP_REPO_DIR.

Зрелость и ограничения Swamp

Swamp — инструмент на ранней стадии развития. Он активно поддерживается в репозиториях swamp-club и выпускается в виде непрерывных релизов с датой в номере версии. Будьте готовы к изменениям.

• Закрытая модель контрибуций. Код для Swamp пишут только сотрудники Elder Swamp Club. Pull request’ы из форков закрываются автоматически, поэтому сообщения об ошибках и идеи новых функций подаются через swamp issue bug или swamp issue feature, а мейнтейнеры сами реализуют те, что принимают.
• Телеметрия. Swamp собирает телеметрию использования, если её не отключить. Отключить её можно для одной команды флагом --no-telemetry, для сеанса оболочки — переменной SWAMP_NO_TELEMETRY=1, для репозитория — параметром telemetryDisabled: true в .swamp.yaml, а для всех запусков на вашей машине — командой swamp config set telemetry.collection disabled, которая записывает настройку в ~/.config/swamp/telemetry.yaml.
• Область применения. Однострочному скрипту или cron-задаче не нужны модели, DAG и версионируемые данные. Swamp окупается, когда задача охватывает несколько систем, требует истории или используется всей командой.
• Расширения исполняют код. Проверяйте сторонние расширения, прежде чем им доверять.
• Лицензия. AGPL-3.0 с исключением Swamp Extension and Definition Exception.

Детерминированный исполнитель повторяет плохой воркфлоу так же точно, как и хороший. Проверки (assertions) и ревью человеком по-прежнему необходимы.

Заключение

Swamp сохраняет процедуру, а не ход мыслей агента. Сохранённые определения и воркфлоу обеспечивают одинаковые шаги и одинаковые контрольные точки при каждом прогоне, а агент остаётся свободным (и непредсказуемым) всякий раз, когда пишет или изменяет их. Хороший следующий шаг — выбрать один процесс, который ваш агент уже выполняет хорошо, например предрелизную проверку или проход ревью, и попросить его сохранить этот процесс как воркфлоу Swamp. Проверьте YAML, закоммитьте его и запустите из другой агентной среды, чтобы убедиться, что он работает и там.

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

Как запустить воркфлоу Swamp в CI на GitHub Actions?

Используйте swamp-club/setup-swamp — официальный GitHub Action. Он устанавливает Swamp с помощью официального скрипта установки и может также выполнить вход на swamp.club, если передать входной параметр api-key. Установите repo-init в true, чтобы после установки выполнилась команда swamp repo init. Следующий шаг вызывает swamp workflow run с именем воркфлоу. Если прогон завершается сбоем, команда возвращает ненулевой код и задание падает. Action пока находится на ранней версии v0.1.

Где хранить секреты для воркфлоу Swamp?

Поместите их в хранилище секретов (vault) Swamp и ссылайтесь на них по имени в определениях и воркфлоу. Swamp получает реальное значение в момент выполнения шага. Благодаря этому секрет не попадает ни в ваши YAML-файлы, ни в данные .swamp, и ничего не сохраняется для следующего прогона. Встроенный локальный провайдер шифрования не требует дополнительной настройки. Другие провайдеры хранилищ держат секреты во внешних сервисах, таких как AWS Secrets Manager, Azure Key Vault или 1Password.

Нужен ли ИИ-агент для запуска воркфлоу Swamp?

Нет. swamp workflow run — обычная команда CLI, поэтому сохранённый воркфлоу может запустить разработчик, задание CI или скрипт без какого-либо агента. Агент нужен только для создания или редактирования моделей, определений и воркфлоу. Для прогонов, которые никто не запускает вручную, swamp serve может запускать воркфлоу по cron-триггеру. Также он может запускать его при поступлении подписанного вебхука от GitHub, Jira, Linear, Stripe, Slack или универсального эндпоинта.

Можно ли установить Swamp на Windows?

Да. Релизы Swamp на странице релизов swamp-club/swamp на GitHub наряду со сборками для macOS и Linux включают архив swamp-windows-x86_64.zip, содержащий swamp.exe. Однострочная команда с curl передаёт скрипт установки в sh, поэтому в Windows она не работает. Пользователи Windows скачивают релизный архив, извлекают swamp.exe и помещают его в каталог, указанный в PATH.