Руководство по настройке автоматизаций

В этом руководстве описано, как настроить автоматизации в AIKraft Agents для автоматизации рабочих процессов на основе событий.

Рекомендуемый подход — CLI: используйте команды craft-agent automation ... вместо прямого редактирования JSON.

• craft-agent automation --help
• Канонический справочник команд: craft-cli.md

Что такое автоматизации?

Автоматизации позволяют автоматически запускать действия при наступлении определённых событий в AIKraft Agents. Вы можете:

• отправлять запросы для создания сессий агента на основе событий;
• отправлять webhook HTTP-запросы во внешние сервисы (Slack, Discord, собственные API и т. д.);
• выполнять действия по расписанию с использованием cron-выражений;
• автоматизировать рабочие процессы на основе изменений режима прав, флагов или статуса сессии.

Расположение файла automations.json

Автоматизации настраиваются в файле automations.json в корне вашего workspace:

~/.craft-agent/workspaces/{workspaceId}/automations.json

Рекомендуемые команды CLI

craft-agent automation list
craft-agent automation get <id>
craft-agent automation create --event UserPromptSubmit --prompt "..."
craft-agent automation update <id> --json '{...}'
craft-agent automation enable <id>
craft-agent automation disable <id>
craft-agent automation duplicate <id>
craft-agent automation history [<id>] --limit 20
craft-agent automation last-executed <id>
craft-agent automation test <id> --match "..."
craft-agent automation lint
craft-agent automation validate

Базовая структура

{
  "version": 2,
  "automations": {
    "EventName": [
      {
        "name": "Optional display name",
        "matcher": "regex-pattern",
        "actions": [
          { "type": "prompt", "prompt": "Check for updates and report status" }
        ]
      }
    ]
  }
}

Поддерживаемые события

События приложения (генерируются AIKraft Agents)

TodoStateChange — устаревший псевдоним для SessionStatusChange. Существующие конфигурации с прежним именем продолжают работать, но при валидации выводится предупреждение об устаревании.

События агента (передаются в Claude SDK)

Типы действий

Действия с запросом

Отправляет запрос в AIKraft Agents (создаёт новую сессию для запланированных запросов).

{
  "type": "prompt",
  "prompt": "Run the @weather skill and summarize the forecast"
}

Возможности:

• используйте @mentions для ссылок на источники или скиллы;
• переменные окружения подставляются (например, $CRAFT_LABEL).

LLM-подключение и модель: при необходимости укажите, какой провайдер ИИ и какая модель будут использоваться для созданной сессии. Если не указано, применяются значения по умолчанию для workspace.

{
  "type": "prompt",
  "prompt": "Quick code review of recent changes",
  "llmConnection": "my-copilot-connection",
  "model": "gemini-2.5-flash"
}

Значение llmConnection — это slug LLM-подключения, настроенного в настройках ИИ. Значение model — это идентификатор модели, поддерживаемый провайдером. Если значение некорректно или не найдено, система корректно переключается на значение по умолчанию для workspace. Оба параметра можно использовать по отдельности или вместе.

Webhook-действия

Отправляет HTTP-запрос на внешний endpoint при срабатывании события. Полезно для уведомлений (Slack, Discord), записи логов во внешние сервисы или запуска внешних рабочих процессов.

{
  "type": "webhook",
  "url": "https://hooks.slack.com/services/${CRAFT_WH_SLACK_PATH}",
  "method": "POST",
  "body": {
    "text": "Session ${CRAFT_SESSION_NAME} status changed to ${CRAFT_NEW_STATE}"
  }
}

Валидация URL: литеральные URL валидируются при загрузке конфигурации. URL с шаблонами (содержащие $VAR) валидируются во время выполнения после подстановки переменных. Оба варианта должны разрешаться в http:// или https:// — другие протоколы отклоняются.

Формат тела:

• json (по умолчанию) — тело сериализуется в JSON. Заголовок Content-Type: application/json устанавливается автоматически, если вы не переопределили его в headers.
• form — ключи объекта тела кодируются в URL как application/x-www-form-urlencoded. Полезно для OAuth-эндпоинтов, Stripe и устаревших API. Каждое значение поддерживает подстановку $VAR.
• raw — тело отправляется как обычная строка. Установите Content-Type в headers самостоятельно.

Аутентификация:

Вместо ручного создания заголовков Authorization можно использовать сокращённый синтаксис auth:

Bearer-токен:

{
  "type": "webhook",
  "url": "https://api.example.com/events",
  "auth": {
    "type": "bearer",
    "token": "${CRAFT_WH_API_TOKEN}"
  },
  "body": { "event": "$CRAFT_EVENT" }
}

Basic-аутентификация (имя пользователя/пароль):

{
  "type": "webhook",
  "url": "https://legacy.example.com/webhook",
  "auth": {
    "type": "basic",
    "username": "${CRAFT_WH_USER}",
    "password": "${CRAFT_WH_PASS}"
  }
}

Поле auth применяется до пользовательских headers, поэтому при необходимости можно переопределить сгенерированный заголовок Authorization. Все значения полей auth поддерживают подстановку $VAR.

Захват ответа: по умолчанию тела ответов webhook отбрасываются после чтения (для освобождения соединений). Установите captureResponse: true, чтобы захватить тело ответа (обрезается до 4 КБ). Захваченное тело включается в результат выполнения и записывается в историю автоматизации (обрезается до 500 символов).

{
  "type": "webhook",
  "url": "https://api.example.com/status",
  "method": "GET",
  "captureResponse": true
}

Захват ответа увеличивает потребление памяти пропорционально размеру ответа. Включайте только для эндпоинтов, где необходимо проверить ответ.

Подстановка переменных: поля url, значения headers, body и auth поддерживают синтаксис $VAR и ${VAR} для подстановки переменных окружения. См. раздел «Переменные окружения» ниже.

Безопасность: webhook-действия имеют доступ только к системным переменным CRAFT_* и пользовательским секретам CRAFT_WH_*. Они не имеют доступа к полному системному окружению (например, $HOME, $PATH или другие переменные процесса).

Переменные окружения

Действия с запросом и webhook поддерживают подстановку переменных с использованием синтаксиса $VAR или ${VAR}.

Системные переменные (CRAFT_*)

Они автоматически устанавливаются системой автоматизаций на основе срабатывающего события:

Переменные по событиям:

Пользовательские секреты webhook (CRAFT_WH_*)

Для webhook-действий вы можете определить собственные секреты, установив переменные окружения с префиксом CRAFT_WH_ в профиле shell (например, ~/.zshrc, ~/.bashrc):

# In your shell profile
export CRAFT_WH_SLACK_URL="https://hooks.slack.com/services/T.../B.../xxx"
export CRAFT_WH_DISCORD_URL="https://discord.com/api/webhooks/123/abc"
export CRAFT_WH_API_TOKEN="your-secret-token"

Затем ссылайтесь на них в automations.json:

{
  "type": "webhook",
  "url": "${CRAFT_WH_SLACK_URL}",
  "method": "POST",
  "body": { "text": "Hello from Craft Agent!" }
}

{
  "type": "webhook",
  "url": "https://api.example.com/events",
  "headers": { "Authorization": "Bearer ${CRAFT_WH_API_TOKEN}" },
  "body": { "event": "${CRAFT_EVENT}", "session": "${CRAFT_SESSION_NAME}" }
}

Это позволяет не хранить секреты в automations.json (который может быть общим или добавленным в систему контроля версий).

В webhook-действия подставляются только переменные с префиксом CRAFT_WH_. Другие переменные окружения (например, $HOME или $DATABASE_URL) недоступны для webhook.

Переменные окружения не подставляются при тестовом запуске (кнопка «Тест» в интерфейсе). Тесты отправляют URL/тело в исходном виде, как настроено.

Настройка матчера

Отображаемое имя

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

{
  "name": "Morning Weather Report",
  "cron": "0 8 * * *",
  "actions": [
    { "type": "prompt", "prompt": "Run the @weather skill" }
  ]
}

Сопоставление по regex (для большинства событий)

Используйте поле matcher для фильтрации событий, которые запускают ваши автоматизации:

{
  "matcher": "^urgent$",
  "actions": [
    { "type": "prompt", "prompt": "An urgent label was added. Review the session and summarise the issue." }
  ]
}

Если matcher не указан, автоматизация срабатывает для всех событий данного типа.

Сопоставление по cron (для SchedulerTick)

Для событий SchedulerTick используйте cron-выражения вместо regex:

{
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "actions": [
    { "type": "prompt", "prompt": "Give me a morning briefing" }
  ]
}

Формат cron: минута час день-месяца месяц день-недели

Примеры:

• */15 * * * * — каждые 15 минут
• 0 9 * * * — ежедневно в 9:00
• 0 9 * * 1-5 — по будням в 9:00
• 30 14 1 * * — 1-го числа каждого месяца в 14:30

Часовой пояс: используйте имена часовых поясов IANA (например, Europe/Budapest, America/New_York). Если не указан, применяется системный часовой пояс.

Условия

Условия — это необязательные фильтры, которые выполняются после совпадения matcher/cron, но до срабатывания действий. Все условия в массиве должны выполниться (неявное И). Если массив пуст или не указан, действия выполняются без условий.

{
  "cron": "0 9 * * *",
  "timezone": "Europe/Budapest",
  "conditions": [
    {
      "condition": "time",
      "weekday": ["mon", "tue", "wed", "thu", "fri"]
    }
  ],
  "actions": [
    { "type": "prompt", "prompt": "Good morning! Here's your daily briefing." }
  ]
}

Временные условия

Проверяет время суток и день недели в указанном часовом поясе.

{
  "condition": "time",
  "after": "09:00",
  "before": "17:00",
  "weekday": ["mon", "tue", "wed", "thu", "fri"],
  "timezone": "Europe/Bustapest"
}

Ночные диапазоны: если after позже before (например, "after": "22:00", "before": "06:00"), диапазон переходит через полночь.

Условия по состоянию

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

{
  "condition": "state",
  "field": "permissionMode",
  "from": "safe",
  "to": "allow-all"
}

Поля переходов: для permissionMode и sessionStatus значения from/to автоматически сопоставляются с правильными ключами полезной нагрузки (oldMode/newMode, oldState/newState).

Логическая композиция

Комбинируйте условия с помощью and, or и not:

{
  "condition": "and",
  "conditions": [
    { "condition": "time", "weekday": ["mon", "tue", "wed", "thu", "fri"] },
    { "condition": "time", "after": "09:00", "before": "17:00" }
  ]
}

{
  "condition": "or",
  "conditions": [
    { "condition": "state", "field": "permissionMode", "value": "allow-all" },
    { "condition": "state", "field": "isFlagged", "value": true }
  ]
}

{
  "condition": "not",
  "conditions": [
    { "condition": "time", "weekday": ["sat", "sun"] }
  ]
}

Глубина вложенности: условия можно встраивать на глубину до 8 уровней. На глубине 4 выводится предупреждение о возможности упрощения. Неизвестные типы условий отказывают безопасно (выполняются с результатом false).

Режим прав

Поле permissionMode управляет уровнем прав сессий, создаваемых действиями с запросом.

{
  "cron": "*/10 * * * *",
  "permissionMode": "allow-all",
  "actions": [
    { "type": "prompt", "prompt": "Check system health and log the results" }
  ]
}

Режимы прав:

• safe — сессия работает в режиме Изучение (по умолчанию)
• ask — сессия запрашивает подтверждение перед операциями записи
• allow-all — сессия автоматически подтверждает все операции

Лейблы для действий с запросом

Действия с запросом могут указывать лейблы, которые будут применены к создаваемой сессии:

{
  "cron": "0 9 * * *",
  "labels": ["Scheduled", "morning-briefing"],
  "actions": [
    { "type": "prompt", "prompt": "Give me today's priorities" }
  ]
}

Это создаёт сессию с автоматически применёнными лейблами «Scheduled» и «morning-briefing».

Маршрутизация тем Telegram

Когда супергруппа Telegram связана в Настройки → Сообщения → Telegram, установите telegramTopic в матчере, чтобы направлять создаваемые сессии в отдельную тему форума. Тема создаётся при первом использовании и переиспользуется далее.

{
  "matcher": "^urgent$",
  "telegramTopic": "Urgent Alerts",
  "actions": [
    { "type": "prompt", "prompt": "Look at the urgent issue: $LABEL" }
  ]
}

Требования для активации (все должны выполняться; иначе поле будет проигнорировано):

• супергруппа Telegram связана в Настройках → Сообщения → Telegram;
• бот Telegram подключён;
• бот имеет право администратора «Управление темами».

Имена чувствительны к регистру: "Reports" и "reports" создают разные темы.

Настройка супергруппы Telegram

Если вы ещё не связали супергруппу:

1. Создайте или преобразуйте супергруппу с включёнными темами. В Telegram откройте группу → нажмите на название группы → Изменить (иконка карандаша) → включите Темы → Сохранить. Группа должна быть форум-супергруппой; обычные группы не поддерживают темы.
2. Добавьте бота в супергруппу. Название группы → Добавить участников → найдите имя вашего бота → добавьте.
3. Назначьте бота администратором с правом «Управление темами». Название группы → Изменить → Администраторы → Добавить администратора → выберите бота → включите Управление темами → Сохранить. Этот шаг чаще всего пропускают; без него создание темы завершится ошибкой 400: not enough rights to create a topic.
4. Свяжите супергруппу. В AIKraft Agents: Настройки → Сообщения → Telegram → Связать супергруппу. Скопируйте 6-значный код, затем в любой теме супергруппы введите /pair <code>. Бот подтверждает, а строка в настройках обновляется названием группы.

Проверьте, что в строке супергруппы в настройках отображается название группы. Если позже запуски автоматизаций завершатся ошибкой, в ~/.craft-agent/logs/messaging-gateway.log будет отображаться automation_topic_bind_failed с исходной ошибкой Telegram.

Полные примеры

Ежедневный прогноз погоды

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "name": "Daily Weather Report",
        "cron": "0 8 * * *",
        "timezone": "Europe/Budapest",
        "labels": ["Scheduled", "weather"],
        "actions": [
          { "type": "prompt", "prompt": "Run the @weather skill and give me today's forecast" }
        ]
      }
    ]
  }
}

Новости ИИ только в будни (с условиями)

Используйте условие time, чтобы ограничить ежедневное расписание только буднями:

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "name": "Morning AI news",
        "cron": "0 9 * * *",
        "timezone": "Europe/Budapest",
        "conditions": [
          {
            "condition": "time",
            "weekday": ["mon", "tue", "wed", "thu", "fri"],
            "timezone": "Europe/Budapest"
          }
        ],
        "labels": ["Scheduled", "ai-news"],
        "actions": [
          { "type": "prompt", "prompt": "Run the @ai-news skill and summarize today's AI developments" }
        ]
      }
    ]
  }
}

Фильтр по режиму прав (с условиями)

Уведомляйте только при изменении режима прав именно с safe на allow-all:

{
  "version": 2,
  "automations": {
    "PermissionModeChange": [
      {
        "conditions": [
          {
            "condition": "state",
            "field": "permissionMode",
            "from": "safe",
            "to": "allow-all"
          }
        ],
        "actions": [
          {
            "type": "webhook",
            "url": "${CRAFT_WH_SLACK_URL}",
            "method": "POST",
            "body": { "text": ":warning: Permission escalated from safe to allow-all in *${CRAFT_SESSION_NAME}*" }
          }
        ]
      }
    ]
  }
}

Логирование изменений лейблов

{
  "version": 2,
  "automations": {
    "LabelAdd": [
      {
        "actions": [
          { "type": "prompt", "prompt": "The label $CRAFT_LABEL was added. Log this change with a timestamp." }
        ]
      }
    ],
    "LabelRemove": [
      {
        "actions": [
          { "type": "prompt", "prompt": "The label $CRAFT_LABEL was removed. Log this change with a timestamp." }
        ]
      }
    ]
  }
}

Уведомление о срочном лейбле

{
  "version": 2,
  "automations": {
    "LabelAdd": [
      {
        "matcher": "^urgent$",
        "actions": [
          { "type": "prompt", "prompt": "An urgent label was added to this session. Triage the session and summarise what needs immediate attention." }
        ]
      }
    ]
  }
}

Уведомление об изменении режима прав

{
  "version": 2,
  "automations": {
    "PermissionModeChange": [
      {
        "matcher": "allow-all",
        "actions": [
          { "type": "prompt", "prompt": "The permission mode was changed to allow-all. Log the change and note any security implications." }
        ]
      }
    ]
  }
}

Уведомление в Slack при изменении статуса

Отправляет сообщение в Slack, когда сессия помечается как завершённая. Требуется CRAFT_WH_SLACK_URL в профиле shell.

{
  "version": 2,
  "automations": {
    "SessionStatusChange": [
      {
        "name": "Notify Slack on Done",
        "matcher": "^done$",
        "actions": [
          {
            "type": "webhook",
            "url": "${CRAFT_WH_SLACK_URL}",
            "method": "POST",
            "body": {
              "text": ":white_check_mark: Session *${CRAFT_SESSION_NAME}* marked as done"
            }
          }
        ]
      }
    ]
  }
}

Смешанные действия (запрос + webhook)

Одна автоматизация может содержать и действия с запросом, и webhook. Они выполняются по порядку.

{
  "version": 2,
  "automations": {
    "LabelAdd": [
      {
        "name": "Urgent: Notify and Triage",
        "matcher": "^urgent$",
        "actions": [
          {
            "type": "webhook",
            "url": "${CRAFT_WH_SLACK_URL}",
            "method": "POST",
            "body": { "text": ":rotating_light: Urgent label added to *${CRAFT_SESSION_NAME}*" }
          },
          {
            "type": "prompt",
            "prompt": "An urgent label was added. Triage the session and summarise what needs immediate attention."
          }
        ]
      }
    ]
  }
}

Form-кодированный запрос (OAuth / Stripe)

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "name": "Refresh API Token",
        "cron": "0 */6 * * *",
        "actions": [
          {
            "type": "webhook",
            "url": "https://auth.example.com/oauth/token",
            "method": "POST",
            "bodyFormat": "form",
            "body": {
              "grant_type": "client_credentials",
              "client_id": "${CRAFT_WH_CLIENT_ID}",
              "client_secret": "${CRAFT_WH_CLIENT_SECRET}"
            }
          }
        ]
      }
    ]
  }
}

Webhook с пользовательскими заголовками

{
  "version": 2,
  "automations": {
    "SessionStatusChange": [
      {
        "name": "Log to External API",
        "actions": [
          {
            "type": "webhook",
            "url": "https://api.example.com/craft-events",
            "method": "POST",
            "headers": {
              "Authorization": "Bearer ${CRAFT_WH_API_TOKEN}",
              "X-Source": "craft-agent"
            },
            "body": {
              "event": "${CRAFT_EVENT}",
              "session_id": "${CRAFT_SESSION_ID}",
              "old_status": "${CRAFT_OLD_STATE}",
              "new_status": "${CRAFT_NEW_STATE}"
            }
          }
        ]
      }
    ]
  }
}

Валидация

Автоматизации валидируются в следующих случаях:

1. workspace загружается;
2. вы редактируете automations.json (через хук PreToolUse);
3. вы запускаете config_validate с target automations или all.

Использование config_validate:

Попросите AIKraft Agents валидировать конфигурацию автоматизаций:

Validate my automations configuration

Или используйте инструмент config_validate напрямую с target: "automations".

Частые ошибки валидации:

• некорректный синтаксис JSON;
• неизвестные имена событий;
• пустой массив actions;
• некорректное cron-выражение;
• некорректный часовой пояс;
• некорректный regex-шаблон;
• потенциально небезопасные regex-шаблоны (вложенные квантификаторы).

Ручная валидация:

# Check automations.json syntax
cat automations.json | jq .

Поведение при повторных попытках

Webhook-действия имеют два уровня автоматического повторения:

Немедленное повторение (временные сбои)

Если webhook завершается ошибкой сервера (5xx), таймаутом или ошибкой соединения, он автоматически повторяется до 2 раз с экспоненциальным backoff (1с → 2с → 4с). Ошибки клиента (4xx) не повторяются — они указывают на проблему с конфигурацией.

Отложенное повторение (продолжительные сбои)

Если все немедленные повторения завершаются неудачей, webhook добавляется в постоянную очередь повторений. Очередь повторяет с нарастающими интервалами:

После неудачи последнего отложенного повторения webhook помечается в истории как окончательно провалившийся. Отложенные повторения сохраняются при перезапуске приложения.

Повторяются только временные сбои (5xx, таймауты, ошибки соединения). Ошибки клиента (4xx) указывают на проблему с конфигурацией и должны быть исправлены в automations.json.

Повторения и ограничения частоты: повторяемые запросы webhook учитываются в ограничении частоты на эндпоинт (30/мин на источник). Если повторение превысит лимит, оно откладывается до следующего окна повторений.

Ограничения частоты

Для защиты от неконтролируемых автоматизаций (например, автоматизация, которая косвенно запускает саму себя в цикле), шина событий применяет ограничения частоты по типу события:

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

Пример: если у вас есть задача LabelAdd, которая запускает запрос, добавляющий лейбл обратно в сессию, она сработает не более 10 раз до ограничения частоты — это предотвращает бесконечное создание сессий.

Устранение неполадок

Автоматизация не срабатывает

1. Проверьте имя события — оно должно быть точным (например, LabelAdd, а не labeladd).
2. Проверьте matcher — regex должен совпадать со значением события.
3. Проверьте cron — для SchedulerTick проверьте cron-выражение с помощью онлайн-инструмента.
4. Проверьте логи — ищите [automations] или [Scheduler] в логах.

Запрос не создаёт сессию

1. Проверьте, что запрос не пуст.
2. Убедитесь, что @mentions ссылаются на действующие источники/скиллы.

Webhook не работает

1. Проверьте URL — должен быть валидным http:// или https:// URL. Другие протоколы (ftp, ws и т. д.) отклоняются во время выполнения с понятной ошибкой.
2. Проверьте переменные окружения — убедитесь, что переменные CRAFT_WH_* установлены в профиле shell и AIKraft Agents был перезапущен после их добавления. URL с шаблонами $VAR валидируются после подстановки переменных — если переменная пуста или не установлена, URL будет некорректным.
3. Используйте кнопку «Тест» — проверяет подключение к URL (примечание: переменные окружения не подставляются при тесте).
4. Проверьте метод — некоторые эндпоинты требуют определённых HTTP-методов (POST, PUT и т. д.).
5. Проверьте ответ — история автоматизации показывает HTTP-коды состояния для выполнений webhook.

Повторение неудачных webhook

Если выполнение webhook завершается ошибкой (отображается красным индикатором в таймлайне), вы можете повторить его:

1. Откройте страницу деталей автоматизации.
2. В таймлайне «Недавняя активность» неудачные записи webhook отображают кнопку «Повторить».
3. Нажмите «Повторить», чтобы немедленно повторно выполнить webhook-действия.
4. Результат повторения записывается как новая запись в истории.

Повторения выполняют webhook-действия в текущей конфигурации. Если вы изменили URL или headers после первоначальной ошибки, повторение использует обновлённую конфигурацию. Переменные окружения не подставляются при повторении (как и при нажатии кнопки «Тест»).

Рекомендации

1. Начните с простого — протестируйте базовый запрос перед созданием сложных рабочих процессов.
2. Используйте лейблы — помечайте запланированные сессии для удобной фильтрации.
3. Будьте конкретны — используйте matcher, чтобы избежать срабатывания на каждое событие.
4. Тестируйте cron — используйте crontab.guru для проверки выражений.
5. Не храните секреты в конфигурации — используйте переменные окружения CRAFT_WH_* для URL и токенов webhook вместо их прямого указания в automations.json.
6. Комбинируйте действия — используйте и webhook, и запросы в одной автоматизации для рабочих процессов «уведомление + ответ ИИ».