Воркфлоу¶

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

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

Что можно построить¶

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

Шаг «Преобразование» — проход через модель, который превращает неструктурированный ввод в фиксированный набор полей: достать адрес из письма с заказом, отнести обращение к категории, оценить лид. У него нет инструментов, и он ничего не ищет, поэтому это быстрый и предсказуемый выбор, когда шаг сводится к «прочитай это и верни такие-то поля».
Шаг «Агент» — шаг с рассуждением, который может пользоваться инструментами и делать несколько ходов, чтобы прийти к ответу. Он получает только то, что ему дал билдер: собственные инструменты агента, его знания, его скиллы, подключённую интеграцию; см. Что можно дать шагу «Агент» ниже. Его инструменты не ограничиваются поиском: шаг «Агент» может вызвать всё, что ему дали, включая инструмент, который что-то меняет, — записать файл, оставить комментарий, одобрить заявку, создать запись. Это касается и Google Workspace: шаг может читать календарь, таблицу или документ, а если доступ агента к Google это позволяет — и записывать в них. Это касается и почты, подключённой для агента: шаг может читать эту почту и искать в ней, а также отвечать, отправлять и пересылать письма с неё, в том числе с файлами. См. Подключённая почта. Билдер выбирает этот шаг, когда нужно суждение или поиск: изучить тему, выяснить, почему число выглядит странно, пройти по следу через несколько источников. Шаг работает в собственных лимитах, поэтому останавливается, а не уходит в сторону (см. Лимиты ниже). Шаг «Агент» может работать не больше часа. После этого он останавливается, а запуск завершается ошибкой, а не частичным результатом.
Вызов агента — выполняет одного агента от начала до конца: агента этого воркфлоу или агента, подключённого к нему. Шаг возвращает один фрагмент текста, которым может воспользоваться следующий шаг. См. Вызов агента.
Шаг «Действие» — один вызов того, к чему подключён агент: создать страницу в Notion, получить список задач, завести запись. Модель не запускается — шаг делает ровно этот один вызов с переданными ему значениями.
Шаг «Запись в базу» — записывает строки в базу данных агента, каждое значение — в именованный столбец. Таблица должна уже существовать; если её нет, попросите билдера спроектировать её, прежде чем настраивать запись. Шаг сопоставляет строки по ключу, поэтому повторный запуск воркфлоу обновляет записанное в прошлый раз, а не плодит дубликаты. Для участника команды с общей базой данных команды настройка шага База данных может указывать либо на собственную базу агента, либо на общую базу команды. В интерфейсе называется Запись в базу.
Шаг «Скрипт» — выполняет код, когда нужна точная детерминированная логика. Он читает и пишет собственную базу данных агента через вспомогательную функцию db_query(sql, params), а у участника команды с общей базой данных команды рядом с ней есть вторая — team_db_query(sql, params).
Шаг «Уведомление» — отправляет результат через вебхук, по почте или в Telegram по шаблону сообщения. Письмо уходит из почтового ящика платформы, и вам ничего не нужно настраивать; поля SMTP заполняйте, только если хотите отправлять письма со своего почтового сервера. Это одно заранее подготовленное сообщение, которое отправляется одинаково при каждом запуске. Это не та почта, что подключена в интеграциях, — ею пользуется шаг «Агент», см. Подключённая почта.
Шаг «Условие» — разветвляет поток по выражению.
Шаг «Агент (устаревший)» — прежний LLM-шаг: полный цикл агента через модель (со своими настройками модели, температуры и длины). Воркфлоу, построенные до появления перечисленных выше типов шагов, по-прежнему используют его и продолжают работать как есть; в новых воркфлоу билдер вместо него использует Преобразование и Агент. В интерфейсе называется Агент (устаревший).
Параллельная группа — не отдельный вид шага, а способ выполнить несколько шагов любых перечисленных видов одновременно, а не друг за другом. Как определяется успех группы, см. в разделе Параллельные группы ниже.

Шаги могут передавать результаты дальше — более поздний шаг может ссылаться на вывод более раннего, — а воркфлоу поддерживают переменные ({{like_this}}), чтобы один и тот же воркфлоу можно было использовать с разными входными данными. Шаги Преобразование и Агент заранее объявляют форму своего ответа — какие поля и какого типа, — поэтому более поздний шаг может взять из результата одно поле, а не весь результат целиком как блок текста. Откройте шаг на схеме, чтобы увидеть, какой ввод он принимает и какой вывод объявляет.

Конфигурация. Настройки, которые нужны воркфлоу, собраны в его форме Конфигурация, и поле в ней бывает одного из двух видов:

Поле, которое берётся из одной из интеграций агента — ID чата Telegram, почтовый ящик, ключ MCP-сервера, переменная из Окружения агента, — только отображается, вводить в него ничего нельзя. Подпись говорит, откуда берётся значение, например Из вашего подключения Telegram или Из переменных этого агента; секреты остаются скрытыми, и каждый запуск берёт то значение, которое в этот момент хранится в источнике. Для интеграции это подключение того человека, от имени которого идёт запуск (см. Чей это запуск): его собственное — для интеграции, которую каждый пользователь подключает сам, и владельца — для интеграции, которой владелец делится. Когда показать нечего, поле говорит, кто может это исправить: Не подключено — подключите в окне настройки агента, когда подключить должны вы, или что подключить может только владелец агента.
Собственное поле воркфлоу — сколько элементов, каким получателям — заполняется вручную, и каждый, кто запускает воркфлоу, хранит в нём своё значение.

Секреты, API-ключи и значения из интеграций всегда обязательны: билдер помечает их так, и запуск не начнётся, пока у каждого из них нет значения. Собственные поля воркфлоу заполните в форме; для остальных подключите интеграцию. Значение из подключения Telegram, почтового ящика или MCP-сервера попадает только в собственную настройку этой интеграции в шаге Уведомление: бот и чат Telegram — в сообщение Telegram, адрес, пароль, сервер и порт почтового ящика — в настройки отправки письма. Оно никогда не передаётся в скрипт, вебхук или другой канал, и сохранить воркфлоу, который кладёт его туда, не получится; для ключа, который читает скрипт, используйте переменную из Окружения агента. Воркфлоу, сохранённый раньше и уже кладущий такое значение в другое место, продолжает работать только в запусках самого владельца; в запуске любого другого человека — включая тех, у кого уровень Может редактировать, а также владельцев и администраторов организации — этот шаг останавливается и объясняет причину, чтобы владелец перенёс значение в предназначенную для него настройку. Шаг Уведомление, который отправляет письма с общей почты агента, отправляет их только в запусках владельца, владельцев и администраторов организации и людей с уровнем Может редактировать; в запуске любого другого человека он останавливается и сообщает об этом.

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

Вызов агента¶

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

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

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

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

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

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

Повторная попытка выполняет шаг заново. Если шаг сделал что-то за пределами запуска, например отправил сообщение, при повторе он может сделать это ещё раз.

Параллельные группы¶

Параллельная группа — это набор шагов, которые стартуют вместе и выполняются одновременно, вместо того чтобы воркфлоу ждал окончания одного шага, прежде чем начать следующий. Билдер решает, какие шаги входят в группу, — обычно те, работа которых не зависит от результатов друг друга: например, изучить три не связанные темы или проверить сразу три разных источника. В группу может входить шаг любого типа: «Преобразование», «Агент», «Действие» — что требуется для работы. На схеме воркфлоу группа показана отдельным блоком, который можно развернуть, чтобы увидеть шаги внутри.

Как определяется успех. В группе больше одного шага, поэтому для вопроса «сработала ли группа» нужно отдельное правило — это политика успеха группы, и она бывает одной из трёх:

Все шаги успешны — группа считается успешной, только если ни один её шаг не завершился ошибкой.
Успешен хотя бы один шаг — достаточно одного чистого результата в группе, даже если остальные шаги завершились ошибкой.
Успешны не менее N шагов — вы задаёте число; группа считается успешной, как только столько шагов вернулись без ошибок, независимо от остальных.

Что вы видите при частичном успехе. Откройте запуск, в котором была группа, и вы увидите итоговую фразу вроде «Успешно 3 из 4 шагов — достаточно, политика требует минимум 2»: она говорит, сколько шагов действительно завершились успешно и хватило ли этого для политики. Названная политика — та, которую этот запуск действительно применил; если вы задали своё правило, это будет оно (см. Изменение политики ниже). Запуск, в котором политика не была записана, показывает только, сколько шагов завершились успешно. Если на схеме не показан ни один запуск, для каждой группы указана политика, которую применит следующий запуск. Каждый шаг внутри группы также сохраняет в истории запусков собственный статус, как и любой другой шаг, поэтому вы точно видите, какой из них завершился ошибкой, даже если группа в целом выполнила политику.

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

Изменение политики. Билдер задаёт политику каждой группы, когда пишет воркфлоу. Вы можете задать вместо неё своё правило: откройте карточку Конфигурация воркфлоу, нажмите Изменить и в разделе Группа параллельных шагов выберите, когда группа считается успешной, — «все шаги успешны», «успешен хотя бы один шаг» или «успешны не менее N шагов», — затем нажмите Сохранить. Это одно правило для всех параллельных групп воркфлоу, и оно действует со следующего запуска. Карточка показывает эту настройку, только если в воркфлоу есть хотя бы одна параллельная группа, и предлагает только те числа, которые подходят каждой группе. Вариант билдера — с пометкой «(выбор Билдера)» или «как задал Билдер», когда билдер задал группам разные политики, — возвращает решение билдеру, и каждая группа снова использует политику, которую он ей задал. Если раньше для групп были заданы разные правила, карточка показывает «по-разному в разных группах», пока вы не выберете одно.

Что доступно шагу¶

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

Шаг, который может что-то изменить, а не только посмотреть, несёт прямо на схеме воркфлоу небольшую метку пишет, так что вы видите, какие шаги могут записывать, не открывая каждый из них. Это касается шага «Агент», среди инструментов которого есть записывающий, и шага «Действие», единственный вызов которого что-то записывает. Откройте такой шаг «Агент» или «Действие», и его панель также скажет Может писать через подключённые инструменты — так с первого взгляда понятно, какие шаги только читают, а какие действуют.

Когда запуск завершился, его запись показывает не только то, что шаг мог сделать, но и то, что он сделал, — и для шагов «Агент», и для шагов «Действие». В истории запусков шаг, который действительно вызвал один из таких записывающих инструментов, несёт счётчик Использовано побочных эффектов, а при наведении на него видно, какие инструменты он вызвал. Откройте такой шаг, и в его подробностях эти две вещи разделены: Разрешено в этом запуске — то, что шагу было разрешено, Использовано в этом запуске — то, что он действительно вызвал. Поэтому шаг, который мог записать, но не стал, выглядит иначе, чем шаг, который записал.

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

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

Что можно дать шагу «Агент»¶

Шаг «Агент» получает только то, что ему дал билдер, — больше ничего от агента с ним не приходит. Билдер запрашивает минимум, необходимый шагу, а панель шага перечисляет всё это. Что он может дать:

Собственные инструменты агента — чтение и запись файлов в рабочей папке агента (той же, которой пользуются шаги с кодом), веб-поиск и чтение веб-страниц, подключённый вами браузер и просмотр изображений, созданных запуском. Веб-поиск и чтение веб-страниц расходуют кредиты, которые списываются с того же баланса, что и остальной запуск, и не предлагаются в установке без веб-поиска.
Знания — коллекция из документов агента, чтобы искать в ней или читать из неё документ. Шаг ищет только в тех коллекциях, которые ему дали. Это могут быть и файлы задачи конкретного человека: у агента, который хранит файлы каждого разговора отдельно, — файлы, которые человек приложил к одному из своих разговоров.
Скиллы — один из скиллов агента: его инструкции, его файлы, а для скилла со скриптами — запуск этих скриптов.
Интеграции — операции подключённого MCP-сервера, Google Workspace или почты, подключённой для агента. Интеграция работает через подключение того человека, от имени которого идёт запуск, — см. Чей это запуск. О почте см. Подключённая почта.

Шаг сохраняет все инструменты, которые дал ему билдер. Переключатели в настройках Инструменты агента определяют, чем агент может пользоваться в чате; шаг сохраняет свои инструменты, даже если какой-то из них там выключен. Чтобы забрать инструмент у шага, попросите билдера изменить шаг. Исключение — шаг Агент (устаревший): он запускает самого чат-агента с инструментами, включёнными в настройках Инструменты агента.

Файлы задачи и браузер. Каждый запуск идёт от имени одного человека (см. Чей это запуск), но для файлов задачи и подключённого браузера условие строже: шаг может пользоваться ими, только если этот человек сам начал запуск — нажал Запустить или через собственное расписание. Запуск, начатый вебхуком или агентом из чата, не может читать чьи-либо файлы задачи или управлять чьим-либо браузером, хотя во всём остальном действует от имени человека; и шаг никогда не читает файлы задачи одного человека в запуске другого. Коллекции из документов агента и всё остальное перечисленное выше работают в любом запуске.

На схеме под названием шага указано, что ему дали: скилл — как «Скилл: …», коллекция — как «Знания: …», инструменты и интеграции — по названиям; если их больше четырёх, добавляется +N. Откройте шаг, и его панель перечислит всё, сгруппировав по разделам Инструменты, База знаний, Скиллы и Интеграции, — у каждого пункта однострочное описание и пометки, описанные выше. Когда у двух пунктов одинаковое название — две коллекции, обе называются «Заметки», или файлы задачи из двух разговоров, — они нумеруются: «Заметки (1)» и «Заметки (2)», одинаково на схеме и в панели.

Версии скиллов. Шаг использует ту версию скилла, которая была актуальной, когда билдер его добавил, и продолжает использовать её, когда скилл потом меняется, — так работающий воркфлоу не меняется у вас за спиной. Когда у агента появилась более новая версия, рядом с названием скилла на схеме появляется стрелка — наведите на неё, чтобы увидеть Доступна новая версия, — а панель шага показывает Новая: vN рядом с версией, которую использует шаг. Чтобы перевести шаг на новую версию, попросите билдера — он обновит шаг за вас. Самовосстановление никогда не меняет версию скилла само.

Делается отдельным шагом, а не шагом «Агент». Для выполнения кода и для чтения или записи базы данных через SQL есть свои шаги — шаг «Скрипт» и шаг «Запись в базу», — чтобы эта работа каждый раз выполнялась одинаково. Сообщение, которое воркфлоу отправляет с платформы или с указанного вами почтового сервера, по той же причине — это шаг «Уведомление». Единственное исключение для кода — собственные скрипты скилла, описанные выше, которые панель шага помечает как запускает код. Почта, подключённая для агента, — это не такая рассылка: её можно дать шагу «Агент», и тогда он читает, ищет, отвечает, отправляет и пересылает письма с этого аккаунта. См. Подключённая почта.

Никогда не доступно в фоновом шаге. Некоторые инструменты агента имеют смысл только в живом чате, поэтому их не получает ни один шаг воркфлоу: задать пользователю вопрос, показать что-то на канвасе чата, показать изображения или сослаться на источники в чате, открыть файл, приложенный к текущему чату, или добавить его в знания, работать с собственными воркфлоу агента, собирать агентов и менять структуру базы данных. Сохранение в память, генерация изображений и видео и загрузка с Google Диска шагам воркфлоу пока недоступны. Вызов этого агента или подключённого агента — это отдельный шаг (см. Вызов агента), а не инструмент, который дают шагу «Агент».

Когда то, что дали шагу, пропадает. Если коллекцию или скилл убрали из агента, у скилла нет секрета, браузер не подключён, подключение человека, от имени которого идёт запуск, отсутствует или требует переподключения к тому моменту, когда до него дойдёт шаг, или запуск начат вебхуком либо из чата, а шагу нужен браузер или чьи-то файлы задачи, — шаг останавливается, не сделав никакой работы. Запуск помечается как Нужен ключ или настройка с примечанием, где это исправить, — Скиллы, База знаний, Управление браузером или, для подключения человека, от имени которого идёт запуск, окно настройки агента, где этот человек подключает или переподключает его, — а ошибка шага точно говорит, что нужно изменить. Некоторые из этих проблем исправляет только изменение шага — например, чьи-то файлы задачи в запуске, начатом вебхуком, — и тогда ошибка предлагает попросить билдера изменить шаг. Некоторые может исправить только администратор вашей установки — например, если в установке больше нет веб-поиска; тогда примечание говорит об этом вместо названия панели. Автоматические повторы и самовосстановление такой шаг не трогают, так что кредиты не тратятся на догадки. Запуск по расписанию, остановившийся таким образом, выключает расписание, из которого он пришёл, — как и в случае с Google ниже, — поэтому, исправив настройку, снова включите его. Браузер, который подключён, но в этот момент не в сети, — другой случай: шаг видит ошибку и продолжает как может.

Подключённая почта¶

Шаг «Агент» может работать с почтовым ящиком, который уже подключён для агента в разделе Интеграции. Он может получать список писем, читать письмо, искать, отмечать письмо прочитанным, отвечать, отправлять новое письмо и пересылать письмо. К ответу или новому письму можно приложить файлы, которые уже есть у запуска, — файл, записанный более ранним шагом того же запуска, или файл из рабочей папки человека, от имени которого идёт запуск. При чтении письма можно получить одно из его вложений. При пересылке отправляется текст исходного письма, плюс комментарий, если шаг его добавил; исходные файлы и новые файлы при этом не прикладываются.

На схеме шаг называет эту почту так же, как любую другую интеграцию: вид аккаунта и адрес, например Почта — Gmail и сам адрес. Outlook, Yahoo, Яндекс, Mail.ru и iCloud называются так же. Аккаунт, не входящий в этот список, всё равно показывается как Почта с адресом. Когда адрес вам видеть не положено, шаг пишет использует почту и не показывает чужой адрес. Откройте шаг, и то же название будет в группе Интеграции его панели.

Чью почту открывает запуск, зависит от режима, заданного в интеграциях, — по тому же правилу, что и в разделе Чей это запуск:

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

Это не шаг «Уведомление». «Уведомление» отправляет одно подготовленное сообщение из почтового ящика платформы или с почтового сервера, который вы указали в этом шаге. Он не открывает почтовый ящик и не отправляет письма от имени того, кто подключил почту. Просите у билдера шаг «Уведомление», когда отчёт или оповещение должны каждый раз уходить одинаково. Просите дать шагу «Агент» почту, когда шагу нужно посмотреть письма, ответить на них или написать с этого аккаунта.

Отправка, ответ и пересылка помечаются на шаге как видно вне компании, а каждое обращение к почте — как выход в интернет: это те же пометки, что и в разделе Что доступно шагу.

Субагенты в шаге «Агент»¶

Шаг «Агент» может также передавать части своей работы субагентам — дополнительным запускам того же шага, которые стартуют рядом с ним. Субагент получает ровно то, что дали самому шагу, и ничего сверх: те же инструменты, ту же модель. Он работает над одной частью задачи с чистого листа и возвращает результат шагу. Так шаг справляется с работой вида «сколько бы их ни нашлось» — разобрать каждое обращение, найденное поиском, собрать сведения о каждом найденном конкуренте, — не перебирая все части по очереди в одном длинном разговоре.

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

Лимиты. Субагенты могут быть вложены до трёх уровней (субагент может раздавать работу собственным субагентам и так далее), одна попытка шага (одна попытка выполнить этот шаг — шаг можно повторить внутри запуска отдельно от новой попытки всего запуска) может запустить всего до 20 субагентов, и одновременно работают до 5. В эти 5 входят только субагенты, которые заняты собственной работой: субагент, который просто ждёт своих субагентов, места не занимает, хотя и учитывается в числе «работают», показанном на карточке шага. Каждый субагент работает в тех же пределах, что и сам шаг, — сколько раз он может вызывать модель или инструмент, сколько текста может обработать, сколько может работать, — и его собственный лимит времени включает время ожидания своих субагентов. Общий лимит времени шага увеличивается на время его субагентов: при 20 субагентах по 5 одновременно это может занять до четырёх кругов, каждому из которых отводится столько же, сколько собственный лимит времени шага, — поэтому шаг с субагентами может работать до пяти раз дольше, чем шаг без них. У запуска есть только один подключённый вами браузер, поэтому хорошо построенный шаг передаёт работу с браузером одному субагенту за раз — билдер пишет задачу шага с учётом этого; несколько субагентов, одновременно обращающихся к браузеру, только мешали бы друг другу.

Как следить за их работой. Пока шаг выполняется, на его карточке на схеме есть счётчик — «N субагентов · M работают», — а в панели шага есть раздел Субагенты: дерево всех субагентов, запущенных шагом; каждая строка подписана первой строкой его задачи, а пока субагент работает, показаны таймер и текущий инструмент. Разверните строку, чтобы увидеть всю задачу, вызванные инструменты и ответ; значения из Конфигурации воркфлоу и Окружения агента показываются там как ***. Хорошо составленная задача начинается с короткой строки, называющей её часть, — заголовка истории, названия региона, — так что свёрнутые строки сразу различимы, а не повторяют одни и те же первые слова. Тело вебхука там не скрывается: субагенты хранят его в том виде, в каком оно пришло, как и результаты шагов, а скрывается оно только в том, что поступает в реальном времени, пока шаг выполняется, — см. Использование тела запроса. Субагенты из предыдущей попытки того же шага сворачиваются в одну строку, которую можно открыть, чтобы посмотреть назад. Приложение для Android показывает тот же счётчик на карточке шага.

Ошибка субагента не роняет шаг. Если у субагента возникла проблема — нужный ему сайт недоступен, он упёрся в один из своих лимитов, — шаг получает это как обычный результат, и модель шага решает, что делать дальше: попробовать эту часть иначе, доделать её самой или указать в ответе, что этой части не хватает. Шаг завершается ошибкой только по собственной причине и никогда — из-за субагента.

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

Возобновление. Возобновите запуск, шаг которого был прерван, — и если с тех пор шаг не менялся (самовосстановление его не переписало), он продолжит с тем, что субагенты из прерванной попытки уже успели сделать, а не будет переделывать эту работу. Новый запуск, Перезапустить или шаг, изменённый самовосстановлением, запускают субагентов с нуля.

Стоимость. Стоимость шага уже включает всё, что потратили его субагенты, поэтому ничего дополнительно складывать не нужно, — но шаг с субагентами может стоить заметно больше, чем без них, ведь каждый из 20 возможных субагентов в попытке тратит в пределах собственной копии лимитов шага.

Шаги, которые пишут в таблицу¶

Шаг, который пишет в таблицу Google, записывает текст. Значение, начинающееся с =, сохраняется как эти символы, а не выполняется как формула, а текст, похожий на число или дату, сохраняется ровно в том виде, в каком пришёл, без преобразования. Поэтому номер телефона вроде +7 900 123-45-67 остаётся номером телефона, а не превращается в ошибку формулы, а текст, который воркфлоу взял со страницы, из письма или формы, не может незаметно стать формулой, которая читает другие ячейки и куда-то их отправляет.

Иногда формула и нужна — строка итогов, ссылка между листами. Откройте шаг и снимите флажок Записывать значения как текст; вас попросят подтвердить кнопкой Я доверяю этому шагу, потому что с этого момента всё, что этот шаг записывает начиная с =, выполняется как формула — включая текст, взятый со страницы, из письма или формы. Снова поставить флажок можно без подтверждения. У каждого шага свой флажок, и меняется он в текущей версии воркфлоу: шаг, открытый из более старого запуска, показывает флажок, но изменить его не даёт.

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

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

Дата запуска¶

У каждого запуска своя дата и время: момент, когда он начался, — а для запуска по расписанию это время, на которое он был запланирован, а не момент, когда до него дошёл планировщик. Каждому AI-шагу сообщается эта дата, поэтому шаг, которого просят сделать «сегодняшний отчёт» или «новости этой недели», знает, какой сегодня день, и дата не меняется, когда запуск позже повторяют или возобновляют: запуск, возобновлённый на следующее утро, всё равно пишет отчёт за день, когда он начался. Перезапустить — с начала или с определённого шага — тоже сохраняет дату исходного запуска. Чтобы вставить дату в текст шага, напишите {{run.date}} (например, 2026-09-26), {{run.datetime}} (дата и время) или {{run.timezone}}; шаг «Скрипт» читает те же значения как RUN_DATE, RUN_AT и RUN_TZ. Внутри шага «Скрипт» эти три имени принадлежат платформе: переменная с тем же именем в Окружении агента скрипту там не видна. Дата указывается в UTC, каков бы ни был ваш часовой пояс и в каком бы часовом поясе ни работало расписание, поэтому расписание, которое срабатывает вскоре после полуночи по Москве (UTC+3), несёт дату предыдущего дня.

Лимиты¶

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

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

Воркфлоу, который постоянно упирается в лимиты, не нуждается в бо́льших лимитах. Если поднять потолок для шага, который никогда не заканчивается, просто сдвинется точка, где он остановится, — настоящая проблема в задаче, у которой нет конца («пройди по всем категориям», «собери полный список»). Дайте шагу то, что заканчивается: укажите, на скольких источниках или элементах ему остановиться, или попросите билдера разделить работу на несколько шагов, каждый из которых делает одну часть.

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

Создание и запуск воркфлоу¶

Создание: попросите билдера в чате — опишите нужную автоматизацию («каждое утро делай сводку новых обращений в поддержку и присылай мне на почту»), и он построит воркфлоу. При создании первого воркфлоу для агента автоматически включается возможность «Воркфлоу». После этого можно настроить шаги, переменные и расписание.
Можно попросить и воркфлоу, запускаемый событием: опишите, что должно его запускать («когда в GitLab открывают merge request, отправь сводку в Telegram»), и билдер напишет шаги вокруг входящего события. Чего он сделать не может — так это включить вебхук: выпустить URL и секрет должны вы сами в настройках воркфлоу, и билдер скажет вам сделать это, когда шаги будут готовы.
Ручной запуск: кнопка Запустить у любого воркфлоу. Чтобы воркфлоу можно было запустить, он должен пройти проверку и быть отмечен как Готово.
Запуск по расписанию: задайте расписание с помощью готовых вариантов (каждый час, ежедневно в заданное время, еженедельно, ежемесячно) или собственного выражения. Расписание принадлежит вам: оно запускается от вашего имени, через ваши подключения, по часам своего часового пояса — вашего, когда вы его настраивали, — а у всех остальных, кто запускает воркфлоу, есть собственное расписание, — см. Личные расписания и вебхуки. Если запуск прервался из-за того, что перезапустился сервер на нашей стороне, — а не из-за проблемы в вашем воркфлоу, — он автоматически повторяется с того места, где остановился, до трёх раз с интервалом в несколько минут, и всё это время расписание остаётся включённым; письмо вы получите, только если после этих повторов проблема не исчезнет. То же самое происходит, когда шаг «Скрипт» или шаг «Запись в базу» не может достучаться до сервиса на нашей стороне — того, что выполняет код скрипта, или того, что читает и пишет базу данных агента для любого из этих шагов: шаг сразу повторяется несколько раз, и если сервис всё ещё недоступен, запуск получает те же повторы с интервалом в несколько минут, а расписание остаётся включённым. Самовосстановление не пытается переписать шаг, который и не был сломан, и вас никогда не просят исправить ключ в Окружении для доступа шага к базе данных — этим доступом платформа управляет сама. Более редкая проблема на нашей стороне, не связанная с перезапуском, повторяется иначе, но во всём, что для вас важно, обрабатывается так же: она не считается ошибкой вашего воркфлоу, поэтому расписание остаётся включённым, а вы получаете письмо, а не гадаете, что произошло. Если же запуск по расписанию завершился ошибкой по причине на вашей стороне, ваше расписание выключается, чтобы не повторять снова и снова воркфлоу, который нужно исправить, — только ваше: расписания других людей для того же воркфлоу продолжают работать. Включите его снова, когда исправите воркфлоу. Сохранённое расписание остаётся видно на вкладке Воркфлоу, пока оно выключено, — так вы видите, когда оно срабатывало, — и возвращается в прежнем виде, когда вы снова его включаете.
Отслеживание запусков: История запусков показывает для каждого вашего запуска триггер, статус (завершён, частично, прервано, ошибка), длительность и вывод каждого шага, так что видно, где именно запуск пошёл не так. На вкладке Воркфлоу полоса Активность показывает ваши запуски за последние 24 часа — по дорожке на воркфлоу, по точке на запуск; точки окрашены по статусу запуска, а легенда под полосой объясняет цвета. Можно включить письмо при сбое автоматического запуска — и для запусков по расписанию, и для доставок вебхука; оно приходит человеку, чьё расписание или вебхук начали запуск (см. Когда автоматический запуск завершается ошибкой), — а раздел Стоимость в списке воркфлоу показывает, сколько тратят ваши запуски. Запуски воркфлоу агента другими людьми принадлежат им: вы видите только те, что завершились ошибкой, в виде коротких строк, — см. Что владелец видит в чужих запусках.

Запуск может завершиться частично, а не только успешно или с ошибкой. Каждый шаг может выполниться без ошибок, а воркфлоу всё равно не сделает свою работу — например, вызов API успешен на уровне HTTP, но в ответе сказано, что сама операция не удалась. Если вы объяснили билдеру, как выглядит настоящий успех (см. ниже), запуск, который завершился без ошибок в шагах, но не дотянул до этой планки, получает статус частично, а не завершён. О частичном запуске вы узнаёте так же, как об ошибке, — он входит в описанную выше подписку на письмо при сбое автоматического запуска, — но больше ничего в воркфлоу не меняется: воркфлоу по расписанию продолжает срабатывать (расписание выключает только настоящая ошибка), а самовосстановление не пытается ничего исправлять, потому что ничего не сломалось: воркфлоу отработал ровно так, как построен, и просто не выполнил заданное вами условие.

Как задать, что считается успехом. По умолчанию любой запуск, завершившийся без ошибок в шагах, считается успешным. Когда этого недостаточно, опишите билдеру настоящее условие («считай запуск успешным, только если статус обращения вернулся как „решено“»), и он добавит в воркфлоу проверку успеха, которая может читать вывод любого шага, а не только последнего. Проверка выполняется один раз, сразу после того как завершается последний шаг воркфлоу; запуск, который её не прошёл, получает статус частично, как описано выше. Если ничего не описывать, воркфлоу ведёт себя как всегда — достаточно, чтобы его шаги завершились.

Файлы шага «Скрипт» сохраняются в рабочем пространстве человека, от имени которого идёт запуск. Запуск, который начали вы, идёт от вашего имени, как и запуски по вашему собственному расписанию и вашему собственному вебхуку (см. Чей это запуск). Поэтому файл, созданный шагом «Скрипт» в одном запуске, остаётся на месте, и его могут прочитать следующее срабатывание расписания этого человека, его ручной запуск и его чаты с агентом. Это обычный случай, потому что Максимум параллельных запусков у webhook-триггера по умолчанию равен 1 — см. ниже. Поднимите его выше 1, и каждая доставка вебхука этого воркфлоу получает собственное закрытое файловое пространство на время запуска — сразу, как только поднят сам пул, независимо от того, выполняется ли в этот момент другая доставка, — так что две доставки, которые действительно выполняются одновременно, не могут столкнуться на одном файле. Это закрытое пространство не переходит в следующий запуск, даже в самую следующую доставку. Что любой запуск видит ВСЕГДА, при любой настройке пула: собственные файлы агента и всё, что записал более ранний шаг того же запуска. Если воркфлоу при поднятом пуле нужно помнить что-то между запусками — нарастающий итог, отметку «последнее увиденное», контрольную точку, — не храните это в файле; пусть шаг «Скрипт» сохраняет это там, где оно переживёт запуск, например в собственной базе данных агента. Запуск, который вызывает агента, отличается от обоих этих случаев: его шаги используют временную папку этого запуска и не записывают постоянные файлы агента.

Воркфлоу в приложении для Mac¶

В разделе Воркфлоу билдера для Mac есть всё, что и в вебе: здоровье и стоимость запусков, карточка каждого воркфлоу с его расписанием, текущие запуски, Запустить и Запустить с данными, Исправить с помощью AI или Пересобрать — они отправляют готовое сообщение в чат билдера (пока билдер ещё отвечает, сообщение ждёт в чате, чтобы вы его отправили), — и Удалить. Воркфлоу открывается на собственной странице со схемой шагов, управлением запусками, ожидающими доставками, формой конфигурации, вашим расписанием и вебхуком, историей запусков и стоимостью запусков; оттуда запуск показывает свои шаги, их живой лог и их субагентов, а шаг — своё определение, живой лог и субагентов.

Чей это запуск¶

Каждый запуск идёт от имени одного человека — того, кто стоит за тем, что его начало:

Как начался запуск	Чей это запуск
Нажата кнопка Запустить	того, кто её нажал
Агент начал его из чата	того, кто попросил, — или владельца агента, когда попросил владелец либо владелец или администратор организации, которой владеет владелец агента
Подошло время по расписанию	того, кто настроил это расписание
Был вызван вебхук	того, кто включил этот вебхук

Запуск работает через подключения этого человека. Его MCP-серверы, Google, почта и Telegram — и поля Конфигурации, которые из них берутся, — принадлежат этому человеку для каждой интеграции, для которой владелец выбрал Каждый пользователь — своё, и владельцу — для интеграции, которой владелец делится со всеми (например, Общее (моё подключение) у MCP-сервера или Один общий аккаунт для Google). Поэтому везде, где агент, которым с вами поделились, просит подключить собственный аккаунт, его воркфлоу работают через ваш аккаунт — и никогда незаметно через аккаунт владельца; см. Общие и персональные подключения. Собственные поля Конфигурации воркфлоу содержат значения этого человека, файлы его скриптов попадают в его собственное рабочее пространство, а запуск оплачивается так же, как оплачивался бы чат этого человека с агентом, — см. Кто платит за запуск.

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

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

Перед началом запуска¶

Прежде чем запуск начнёт работу, Агент Атом проверяет, что всё, чем он пользуется, настроено для человека, от имени которого он идёт, — и только то, чем пользуется этот воркфлоу: подключения, к которым обращаются его шаги (MCP-сервер или Google с доступом, нужным его шагам), интеграции, из которых берутся поля его Конфигурации, и собственные значения этого человека для настроек с пометкой Заполняет каждый пользователь. Воркфлоу с шагом Агент (устаревший) запускает целиком чат-агента, поэтому там учитывается каждое подключение агента. Подключение, которое нужно переподключить, тоже останавливает запуск на этом этапе: в чате агент может по ходу дела попросить вас переподключиться, но рядом с запуском нет никого, кто сделал бы это посреди работы.

Нажатие «Запустить» или просьба к агенту в чате проверяются до создания запуска, поэтому отклонённый запуск никогда не попадает в историю запусков. Когда у вас чего-то не хватает, Запустить открывает окно настройки агента — Настройка агента с текстом Прежде чем этот воркфлоу сможет запуститься, подключите нужные аккаунты или укажите значения. — где перечислено только то, что нужно этому воркфлоу; подключите это там и нажмите Продолжить. На вкладке Воркфлоу страницы агента, которым с вами поделились, Запустить вместо этого ведёт на вкладку Подключения той же панели Мои настройки с тем же списком (см. Что видит человек, с которым поделились агентом). В чате агент говорит, какие из ваших подключений настроить в окне настройки, и вы просите снова, когда всё готово. Когда не хватает подключения, которым владелец делится со всеми, вам вместо этого сообщают, что владелец агента его ещё не подключил: исправить это может только владелец в настройках агента.
Запуск по расписанию или доставка вебхука некого спросить, поэтому проверка происходит в момент старта запуска: запуск завершается до первого шага, его ошибка называет, чего не хватает (Для этого воркфлоу не хватает подключений или настроек, которые он использует: …), а человеку, чьё это было расписание или вебхук, приходит сообщение — см. Когда автоматический запуск завершается ошибкой. Запуск по расписанию, остановившийся таким образом, выключает расписание этого человека.
Каждая новая попытка запуска проверяется заново, поэтому «Возобновить» или «Перезапустить» не начнут работу через подключение, которое с тех пор сломалось.
Сначала согласие с условиями агента. У агента, которого построил кто-то другой, человека, который не согласился с тем, что может видеть автор агента, — или не согласился заново после того, как это изменилось, — спрашивают об этом, когда он нажимает Запустить (см. С чем соглашаются посетители). Пока он не согласится, его запуски по расписанию пропускаются без выключения расписания, а в разделе Триггеры показано Приостановлено, пока вы не посмотрите, как агент использует ваши данные; доставки на его вебхук отклоняются с HTTP 409; а агент не может начать для него воркфлоу из чата. В первый раз он получает одно письмо. Уже идущий запуск завершается, а всё остальное возобновляется, как только человек соглашается.

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

Кто платит за запуск¶

Запуск воркфлоу оплачивается так же, как чат с агентом, — для человека, от имени которого идёт запуск. Он может платить из своего личного кошелька или из организации, в которой состоит, или оставить вариант агента по умолчанию (см. Выбор, кто платит).

По умолчанию агента. Человек, от имени которого идёт запуск, платит со своего баланса — того аккаунта, в котором он находился, когда нажал Запустить, попросил в чате, настроил расписание или включил вебхук. Это членство проверяется заново при каждом запуске; если человек с тех пор покинул эту организацию, запуск списывается с его собственного основного аккаунта. Так происходит, пока вы не задали оплату для этого человека.
Оплата, которую вы задали для этого человека. Запуск списывается с вашего баланса — аккаунта, которому принадлежит агент. Собственные запуски владельца, а также запуски владельца или администратора организации, которой владеет владелец агента, всегда списываются с баланса владельца — или, для агента, опубликованного в вашей организации, с баланса организации, как и в чате.
Выбранный кошелёк. Запуск списывается с этого кошелька. Если доступ к нему отозван или кошелёк удалён, новый запуск отклоняется, пока человек не выберет кошелёк заново. Атом не переключает запуск обратно на владельца. Работа, которая уже началась, остаётся на кошельке, с которого началась.
Агент, опубликованный в вашей организации, если человек оставил вариант по умолчанию, списывает с баланса организации и записывает расход на участника, для которого идёт запуск, — так же, как его чаты. Если человек выбрал кошелёк, используется он.

Месячный лимит владельца для этого человека действует только для запусков, которые оплачивает владелец, — с вашего баланса или с баланса организации, если агент опубликован в ней. Запуски, которые человек оплачивает сам, в лимит не засчитываются. Пустой лимит означает отсутствие ограничения. Ноль останавливает новые запуски, за которые платили бы вы. Лимит не распространяется на сборку агента и оценки.

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

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

Агенты, оплачиваемые владельцем, и чужие расписания

Когда вы задали оплату для кого-то, запуски, которые этот человек начинает, оплачиваете вы — его нажатия Запустить, его чаты и каждый запуск его собственных расписаний и вебхуков. Когда человек платит сам, эти запуски оплачивает он, и в месячный лимит они не засчитываются. Разрешить пользователям с доступом запускать воркфлоу включено, пока вы это не выключите; если выключить, люди, с которыми вы поделились агентом, вообще не смогут запускать его воркфлоу (см. Доступ к воркфлоу, знаниям и API).

Личные расписания и вебхуки¶

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

Кто может их настраивать. Владелец агента, владелец или администратор организации, которой владеет владелец агента, и все, с кем поделились агентом, — если в настройках доступа агента включено Разрешить пользователям с доступом запускать воркфлоу; оно включено, пока владелец его не выключит (см. Доступ к воркфлоу, знаниям и API). Владелец настраивает свои в карточке Триггеры воркфлоу; человек, с которым поделились агентом, — в разделе Триггеры карточки воркфлоу на вкладке Воркфлоу страницы агента (см. Что видит человек, с которым поделились агентом). Роль администратора платформы не включает человека в этот список: администратор платформы, с которым агентом не поделились, не может держать на нём собственное расписание или вебхук.

Включение расписания проверяется так же, как нажатие «Запустить», когда вы делаете это сами — в разделе Триггеры или попросив агента в чате. Сначала нужно настроить ваши подключения для этого воркфлоу и заполнить его собственные обязательные поля; если чего-то не хватает, вам покажут, чего именно, так же, как это делает Запустить. Расписание, которое билдер настраивает для владельца, сохраняется без этой проверки; тогда первый запуск проверяет настройку при старте, как любой запуск по расписанию. Выключение расписания этими проверками никогда не задерживается, поэтому сломанное расписание всегда можно остановить. Воркфлоу, который читает тело запроса, вообще нельзя поставить на расписание (см. Использование тела запроса).

Просьба к агенту в чате. «Запускай это для меня каждый понедельник в 9» — агент настроит ваше собственное расписание этого воркфлоу по вашему местному времени, как его сообщает ваш браузер или устройство. Оно сразу включается, поэтому действуют те же проверки, и агент скажет, что настроить, если чего-то не хватает. У вас одно расписание на воркфлоу, поэтому просьба о новом времени заменяет имеющееся. Можно также спросить, какие у вас есть расписания, или попросить отменить одно из них. Когда об этом просит владелец или администратор организации, которой владеет владелец агента, всё это действует на расписание владельца, а не на их собственное, — по тому же правилу, что и запуск, о котором они просят в чате (см. Чей это запуск).

Ваш часовой пояс. Каждое расписание работает по часам своего часового пояса, который показан под выбором времени (Часовой пояс: Europe/Moscow). Новое расписание берёт ваш пояс — тот, который сообщает ваш браузер или устройство в момент сохранения. Существующее расписание при редактировании сохраняет пояс, в котором было сохранено. Старые расписания, сохранённые до того, как у каждого расписания появился собственный часовой пояс, работают в UTC, как и всегда. Когда пояс расписания не совпадает с вашим, выбор времени предлагает Использовать мой часовой пояс (с названием вашего города): он переписывает расписание в вашем поясе так, чтобы оно срабатывало в те же моменты, что и сейчас, — 06:00 по UTC становится 09:00 по Москве, — и вступает в силу при сохранении. Этот вариант предлагается, только если те же моменты можно точно записать в вашем поясе; расписание, которое, например, срабатывает в несколько заданных часов в течение дня, его не получает.

Переход на летнее время. Расписание сохраняет своё местное время при переходе на летнее и зимнее время: расписание на 09:00 срабатывает в 09:00 по часам своего пояса и летом, и зимой. В ночь, когда часы переводят назад, расписание на заданное время суток срабатывает один раз, а не два; в ночь, когда часы переводят вперёд, время, которое часы пропускают (скажем, 02:30), срабатывает в момент перевода. Расписание, которое срабатывает каждый час или каждые несколько минут, следует реальному времени, поэтому срабатывает и в повторяющийся час.

Ваш собственный вебхук. Каждый, кто включает webhook-триггер у воркфлоу, получает собственный адрес и собственный секрет, а доставка на него начинает запуск от его имени. Дедупликация, ограничение частоты, Максимум параллельных запусков и очередь ожидающих доставок действуют для вебхука каждого человека отдельно — см. Webhook-триггер.

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

Когда автоматический запуск завершается ошибкой¶

Если у человека, чьё расписание или вебхук начали запуск, включено Письмо при сбое автоматического запуска воркфлоу в разделе Аккаунт → Профиль → Уведомления, письмо об ошибке приходит ему, а не владельцу агента. Когда письмо касается одного воркфлоу агента, которым владеет этот человек, кнопка в письме и уведомление мобильного приложения открывают этот воркфлоу в билдере; иначе они открывают список агентов этого человека или страницу агента, которым с ним поделились. Запуск по расписанию, завершившийся ошибкой по причине на стороне этого человека, выключает только его расписание; расписания всех остальных для этого воркфлоу продолжают работать. Два случая идут дальше:

Подключение, которым делится владелец, нужно переподключить. Запуск человека, остановившийся по этой причине до первого шага, выключает его расписание — включите его снова, когда владелец переподключит подключение, — и, если эта настройка включена, в письме человеку сказано, что переподключить его должен владелец агента. Владелец тоже получает письмо, если у него включена эта настройка, с просьбой переподключить подключение в настройках агента; собственное расписание владельца не затрагивается.
Платит владелец, и у него закончились кредиты. Расписание человека выключается, и, если эта настройка включена, в письме ему сказано, что у аккаунта, который оплачивает эти запуски, закончились кредиты, — само письмо о закончившихся кредитах приходит тому, кто платит, поэтому так человек узнаёт, почему остановилось его расписание.

Когда человек теряет доступ¶

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

Человек, который покидает агента и удаляет свои данные, сразу теряет свои расписания и вебхуки на воркфлоу этого агента, а его запуски удаляются вместе с остальными его данными.

Воркфлоу у агента, которым поделились¶

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

Что видит человек, с которым поделились агентом¶

Люди, с которыми поделились агентом, получают вкладку Воркфлоу в панели Мои настройки на странице агента — странице опубликованного агента или странице команды для её ведущего агента. Для каждого воркфлоу, который им можно запускать, там показаны название и описание, их собственные значения Конфигурации, Запустить, их собственные расписание и вебхук в разделе Триггеры и их собственные запуски — с простой фразой о причине, если запуск завершился ошибкой. То, что происходит внутри шагов, скрыто (установка может включить показ названий и видов шагов), а Максимум параллельных запусков остаётся настройкой владельца. Запустить и включение расписания проверяются так, как описано в разделах Перед началом запуска и Личные расписания и вебхуки; когда чего-то из их подключений не хватает, их переводят на вкладку Подключения этой панели. Полное описание, написанное для них, — Ваши воркфлоу.

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

Что владелец видит в чужих запусках¶

Свои запуски вы видите полностью, как и раньше. Из чужих запусков:

Здоровье и Стоимость учитывают только ваши собственные запуски. Запуски, которые начинают другие люди, в них не входят — даже те, за которые платите вы и которые по-прежнему списываются с вашего баланса (см. Кто платит за запуск).
Активность показывает только ваши собственные запуски.
Число запусков в сводке публикации агента — только ваши собственные запуски.
История запусков показывает ваши собственные запуски плюс короткую строку для каждого запуска другого человека, который завершился ошибкой, — закончился с ошибкой или был прерван, потому что что-то сломалось по ходу. В строке указано, когда начался запуск, как он был начат, его статус, шаг, на котором он остановился, и вид ошибки, с пометкой Запуск другого человека не завершился — его содержимое скрыто. Строка не открывается: входные данные, вывод, логи и текст ошибки запуска скрыты, как и имя человека. Чужие запуски, которые завершились, которые человек остановил сам (или чьё исправление он остановил) или которые слишком долго ждали в очереди, ошибками не считаются и не показываются.
История запусков также показывает каждый ещё идущий запуск другого человека — строкой с временем начала, способом запуска и статусом Выполняется (или Останавливается), с пометкой Запуск другого человека выполняется — его содержимое скрыто и кнопкой Стоп (где это управление доступно в вашем аккаунте), — чтобы вышедший из-под контроля запуск можно было остановить. Как и строка запуска с ошибкой, она не открывается и не называет человека.
Открывать, возобновлять и перезапускать можно только свои запуски; чужой запуск можно лишь остановить, пока он ещё идёт.
Агент в вашем собственном чате следует тому же правилу: о чужих запусках он может рассказать только о завершившемся ошибкой — когда и как он закончился, на каком шаге и с какой ошибкой.

Ваша собственная опубликованная страница показывает вам ту же вкладку Воркфлоу с вашими собственными расписанием, вебхуком и запусками.

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

Когда шагу нужна интеграция, которую вы не подключили¶

Воркфлоу, использующий Google Workspace, можно построить и опубликовать до подключения Google — это нормальный порядок, и билдер не станет задерживать воркфлоу в ожидании аккаунта Google. Агент Атом сам определяет, что может вызывать каждый шаг Google, поэтому билдер может настроить шаг без аккаунта за ним, а подключение живёт на агенте, а не среди полей Конфигурации воркфлоу, описанных выше. Требование проявляется при первом запуске воркфлоу. Аккаунт Google, который отсутствует, требует переподключения или не дал доступа, нужного шагу, выявляется до начала запуска, как описано в разделе Перед началом запуска, — с обращением к человеку, от имени которого идёт запуск, если речь о его собственном аккаунте, и к владельцу, если речь об одном общем аккаунте агента. То, что разрешают настройки Интеграции агента, проверяет сам шаг: когда сервис выключен или настроен на уровень ниже нужного шагу, шаг останавливается, не сделав никакой работы, запуск помечается как Нужен ключ или настройка с примечанием открыть Интеграции, а ошибка шага в истории запусков точно говорит, что владельцу нужно там включить. Автоматические повторы и самовосстановление такой шаг не трогают, потому что никакое изменение воркфлоу не может подключить аккаунт или изменить настройку, так что кредиты не тратятся на догадки; исправьте настройку и запустите воркфлоу снова. Запуск по расписанию, остановившийся таким образом, также выключает расписание — расписание человека, для которого он шёл, — как и любой запуск по расписанию, остановившийся по причине на стороне человека, поэтому, когда Google будет настроен, снова включите и расписание.

MCP-сервер работает наоборот. Его инструменты — это то, что сообщает сам сервер, поэтому шаг может использовать инструмент только после того, как сервер добавлен к агенту — и авторизован, если он просит войти, — а платформа прочитала список его инструментов. До тех пор билдеру не к чему привязать шаг, и воркфлоу не публикуется; см. Что умеет сервер.

Шаги Google, как и всё остальное, работают с доступом человека, от имени которого идёт запуск (см. Чей это запуск). Если подключение Google у агента настроено как Каждый пользователь подключает свой аккаунт Google, шаг читает и пишет аккаунт Google человека, от имени которого идёт запуск, — в персональном режиме воркфлоу никогда не заимствует аккаунт владельца, и каждый человек подключает свой в окне настройки агента до первого запуска. В режиме Один общий аккаунт каждый запуск использует этот один аккаунт. Оба режима работают для всех типов шагов, включая более старый шаг Агент (устаревший). Уровни сервисов остаются за владельцем: от чьего бы имени ни шёл запуск, шаг может делать только то, что разрешает уровень, заданный для каждого сервиса в интеграциях.

Когда сам Google отвечает ошибкой. В шаге «Действие», который обращается к Google, временная проблема на стороне Google или подключение, которое обрывается или превышает время ожидания, пока шаг общается с Google, автоматически повторяется для любого шага — читает он что-то или добавляет. Ограничение частоты или квота для аккаунта (HTTP 429 или 403, который Google помечает как ограничение частоты) означают, что Google ничего не сделал с запросом; он повторяется после ожидания не меньше того, что просит Google. Ошибки сервера (500, 502, 503, 504), превышения времени ожидания и обрывы соединения тоже повторяются, но они могут прийти уже после того, как Google внёс изменение. Поэтому в шаге, который что-то добавляет или создаёт, — добавляет строки, создаёт событие, документ или файл, — повтор может создать дубликат: лишнюю строку, второе событие. Шаг, который читает или перезаписывает те же ячейки таблицы, дубликата создать не может. Если повторы закончились на шаге, который что-то добавляет, проверьте, было ли внесено изменение — возможно, не один раз, — прежде чем запускать его снова; ошибка шага говорит об этом, когда не удался именно ответ Google. Проблема, которая возникает до того, как запрос шага дошёл до Google, — пока шаг получает доступ к вашему аккаунту Google, когда сервис входа Google ненадолго занят, медленно отвечает или не отвечает, или в этот момент обрывается соединение, — повторяется так же и не может создать дубликат: в Google ещё ничего не отправлено, значит, ничего не могло измениться. Кратковременный сбой стоит лишь повтора, а воркфлоу по расписанию сохраняет расписание. Только если Google продолжает отказывать после автоматических повторов, запуск останавливается, как любой запуск, у которого закончились повторы. Ошибка в самом запросе — несуществующий ID или диапазон (404), значение, которое Google отвергает (400), — не повторяется, потому что повтор дал бы тот же ответ: запуск останавливается со статусом Шаг отклонён и текстом Этот шаг отклонён — политикой воркфлоу или сервисом, к которому он обратился., а ошибка шага называет код и что проверить. Ответ Google, который пришёл, но не может быть прочитан, по той же причине тоже не повторяется и останавливает запуск так же; в шаге, который что-то добавляет, проверьте, было ли внесено изменение, прежде чем запускать его снова. В шаге «Агент» агент сам читает ответ Google и решает, что делать дальше, как с любым инструментом.

Стоимость запуска¶

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

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

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

Итог со знаком ≥ впереди означает, что запуск потратил как минимум столько, а возможно, и больше. Вы увидите его, когда запуск остановили вручную, у него закончились кредиты или платформа прервала его, пока шаг ещё работал. Уже завершившиеся шаги оцениваются как обычно и учитываются; шаг, прерванный на полпути, оплатил сделанную работу, но так и не успел сообщить, сколько именно, поэтому учесть его нельзя. Это число — нижняя граница, а не окончательный счёт.

Запуск, остановленный между шагами, когда ничего не было прервано, показывает точный итог без ≥.

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

Не каждый шаг показывает стоимость. Шаги Действие, Запись в базу, Скрипт, Уведомление и Условие не вызывают модель, поэтому ни один из них не показывает стоимость — это не то же самое, что нулевая стоимость, которая означала бы, что модель работала и ничего не стоила.

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

Стоимость по всем запускам¶

В списке воркфлоу рядом с разделом Здоровье есть раздел Стоимость. Он показывает, сколько потратили ваши собственные запуски воркфлоу агента за последние 7, 14 или 30 дней, — запуски, которые начинают другие люди, не учитываются, даже если платите за них вы (см. Что владелец видит в чужих запусках): итог, среднее на запуск и столбик на каждый день. Таблица ниже разбивает тот же период по воркфлоу — запуски, среднее, медиана и итог. Среднее и медиана считаются по одному и тому же набору запусков — тех, чья стоимость действительно известна, — поэтому несколько дорогих запусков среди них могут сильно поднять среднее над стоимостью типичного запуска; медиана — середина того же набора — стоит рядом как более устойчивый показатель обычного запуска. Если открыть строку, появится график расходов этого воркфлоу во времени — с переключателем За всё время, если нужна вся история, а не выбранный период.

Если открыть воркфлоу и нажать на сводку его стоимости, появятся те же цифры только для этого воркфлоу, плюс его самые дорогие запуски, — так от «в этом месяце вышло дороже» можно сразу перейти к запуску, который это вызвал.

Две вещи эти цифры намеренно не делают. Некоторые запуски появляются в истории, но не выполняют ни одного шага, — чаще всего это запуск по расписанию, сработавший, когда на балансе, который за него платит, закончились кредиты, или запуск, у которого не заполнены обязательные настройки или не настроены подключения. Они учитываются отдельно как Не стартовали и не входят в итог, среднее и медиану; если бы их включали, они тянули бы среднее к нулю, ничего не говоря о расходах. (Когда вы сами нажимаете «Запустить» в тех же условиях, запуск отклоняется ещё до создания, поэтому он не появляется ни в истории, ни в этих цифрах.) Кроме того, у запуска есть стоимость, только если он был оценён во время выполнения: запуски, прошедшие до появления этой функции, и попытки, которые платформа не смогла оценить, показываются как покрытие («Полностью учтено N из M начатых запусков»), а не молча считаются бесплатными, — и, как и не стартовавшие, не входят в среднее и медиану, а не подставляются наугад. Пока хоть один начатый запуск не оценён, итог помечается как нижняя граница; среднее и медиана — никогда: они считаются только по запускам с полностью известной стоимостью, поэтому каждая из них — либо точная цифра, либо, если в периоде ещё ничего не оценено, её нет вовсе.

Как и везде, это стоимость шагов воркфлоу, а не выписка по аккаунту — см. примечание выше.

Webhook-триггер¶

Третий способ запустить воркфлоу — его вызывает другая система. Включите webhook-триггер, и вы получите собственный URL и собственный секрет для воркфлоу, так что запустить его сможет всё, что умеет отправлять HTTP-запросы, — CRM, сервис форм, трекер задач, скрипт другого отдела. Используйте его, когда работа должна происходить когда что-то случается в другом месте, а не по часам. Вебхук принадлежит вам: запуск, который он начинает, идёт от вашего имени, через ваши подключения, а у всех остальных, кто запускает воркфлоу, свой вебхук (см. Личные расписания и вебхуки).

Как включить¶

Раздел Webhook-триггер находится рядом с расписанием в настройках воркфлоу, а у агента, которым с вами поделились, — в разделе Триггеры карточки воркфлоу на вкладке Воркфлоу.

Включить вебхук выпускает URL и секрет. Секрет (он начинается с whk_) показывается один раз, прямо тогда — скопируйте его в вызывающую систему, прежде чем уйти с панели. Потом показываются только его первые несколько символов, рядом с тем, когда вебхук использовался в последний раз.
Обновить секрет заменяет его новым. Старый секрет сразу перестаёт работать, поэтому обновите вызывающую систему тут же.
Отключить вебхук прекращает приём вызовов и не трогает ваше расписание. При повторном включении выдаётся новый секрет: тот, что хранится у отправителя, не оживает, поэтому каждый раз, когда снова включаете вебхук, планируйте обновить отправителя.

Как вызывать¶

Отправьте POST на URL из панели, передав секрет в заголовке. URL указывает и на воркфлоу, и на ваш вебхук — он заканчивается на /hooks/workflows/<workflow-id>/<webhook-id>. Принимаются четыре формы заголовка, поэтому большинство систем можно направить на него напрямую:

Authorization: Bearer <secret> — обычная форма. Просто Authorization: <secret> тоже работает.
X-Webhook-Token: <secret>
X-Gitlab-Token: <secret>
X-Telegram-Bot-Api-Secret-Token: <secret> — задаётся как secret_token при вызове setWebhook в Telegram.

curl -X POST https://app.agentatom.ru/api/hooks/workflows/<workflow-id>/<webhook-id> \
  -H "Authorization: Bearer whk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <the sender's own event id>" \
  -d '{"event": "order.paid", "order_id": "A-1042"}'

Idempotency-Key необязателен, но его стоит отправлять: если один и тот же ключ дважды приходит на один и тот же вебхук, второй вызов отвечает запуском первого, а не начинает новый. Один и тот же ключ, отправленный на вебхуки двух людей, — это два события, и каждое начинает свой запуск. X-Gitlab-Event-UUID от GitLab считается тем же самым.

Прежний адрес

Адрес без части вебхука, …/api/hooks/workflows/<workflow-id>, по-прежнему работает для вебхука владельца агента, поэтому отправителя, которого владелец раньше настроил на него, менять не нужно. Через него проходит только секрет владельца или доставка, подписанная ключами вебхука владельца (см. ниже); на чужой секрет или подпись он отвечает «не найдено». Все остальные используют полный адрес из своей панели.

Проекты GitLab

Вставьте URL в настройки вебхука проекта, а секрет — в собственное поле GitLab Secret token: GitLab не умеет отправлять заголовок Authorization и передаёт это поле как X-Gitlab-Token. Он помечает каждую доставку ID события, что покрывает и дедупликацию.

Отправители, которые подписывают доставки¶

Некоторые сервисы никогда не передают секрет — они подписывают им каждую доставку и отправляют только подпись. Подпись покрывает всё тело запроса, поэтому доставка, изменённая по дороге, отклоняется так же, как доставка с неверным секретом.

Сервисы, в которые можно ввести секрет, — GitHub, Bitbucket, Gitea: вставьте секрет воркфлоу whk_ в соответствующее поле сервиса (в GitHub — Secret вебхука, а Content type установите в application/json).
Сервисы, которые создают собственный секрет, — Linear (lin_wh_…), Sentry, Shopify: скопируйте этот секрет в поле Секрет подписи отправителя на панели webhook-триггера.

Собственный секрет воркфлоу whk_ всегда вставляется в отправителя и никогда — в Секрет подписи отправителя: он и сам проверяет подписанные доставки (вебхуку, включённому до того, как его секрет научился подписывать, сначала нужно один раз Обновить секрет — см. Старые вебхуки ниже), и панель не примет его в это поле.

Подпись принимается, если она совпадает с любым из двух секретов. Распознаваемые заголовки подписи: X-Hub-Signature-256 (GitHub), X-Hub-Signature с sha256= (Bitbucket), X-Gitea-Signature (Gitea), Linear-Signature (Linear), Sentry-Hook-Signature (Sentry), X-Shopify-Hmac-Sha256 (Shopify).

Старые вебхуки

Вебхук, включённый до того, как его секрет научился подписывать доставки, по-прежнему принимает этот секрет в заголовке. Чтобы подписывать им, один раз нажмите Обновить секрет — панель просит об этом, пока это нужно, — и вставьте новый секрет в отправителя. Если вставить старый секрет в Секрет подписи отправителя, он будет отклонён, а сообщение назовёт этот же шаг. Если старый секрет уже стоит в Секрет подписи отправителя, то же обновление убирает его и оттуда.

Сохранённый секрет подписи отправителя потом показывается только первыми несколькими символами, как и собственный секрет вебхука. Удалить очищает его. Обновление секрета whk_ его не трогает — если только в поле не хранится сам старый секрет whk_, который Обновить секрет очищает вместе с ним. Доставка, которая несёт секрет whk_ в заголовке, проверяется только по этому секрету. GitHub и Linear помечают доставки собственным ID события, поэтому дедупликация работает без дополнительной настройки. Gitea тоже помечает свои доставки (как X-GitHub-Delivery), но её Replay отправляет событие с новым ID, поэтому повторно отправленная доставка начинает ещё один запуск. Отправители без распознаваемого заголовка ID доставки (Idempotency-Key, X-Gitlab-Event-UUID, X-GitHub-Delivery, Linear-Delivery) не дедуплицируются, поэтому повторная доставка начинает ещё один запуск, который оплачивается как любой другой, — среди них Bitbucket, Sentry, Shopify и Telegram.

Ответ	Что он означает
202 `queued`	Принято; запуск либо уже выполняется, либо ждёт свободного слота. В ответе есть `run_id`.
202 `duplicate`	Этот ключ уже встречался. Возвращается `run_id` исходного запуска, и ничего нового не начато.
409	Максимум параллельных запусков равен 1, поэтому у человека, чей это вебхук, на этом воркфлоу один слот, и он уже занят — другим его запуском этого воркфлоу, любого вида. Чужие запуски никогда не учитываются. Содержит `Retry-After: 60` — отправьте ещё раз.
409	Воркфлоу не прошёл проверку, поэтому пока не может запускаться.
409	Воркфлоу читает тело запроса, а вызов пришёл без него. Пустой объект (`{}`) считается телом и начинает запуск.
429	Слишком много запросов к этому вебхуку (содержит `Retry-After`) или на балансе, который оплачивает его запуски, закончились кредиты (см. Кто платит за запуск).
429	На этом вебхуке уже 20 доставок ждут слота (содержит `Retry-After`).
413	Тело больше 256 КиБ — это проверяется и при получении, и после подготовки для шагов.
400	Тело не является JSON-объектом (в GitHub установите Content type вебхука в `application/json`) или заголовок `Content-Length` не число.
400	В теле есть значение, которое нельзя сохранить: число слишком большое, чтобы быть настоящим числом (`1e999` и всё остальное, что переполняется, а также `NaN` и `Infinity`, которых нет в JSON), или текст, содержащий NUL или повреждённый символ Unicode. Это касается и имён полей, и значений на любой глубине.
503	Сейчас невозможно подсчитать доставки (содержит `Retry-After`). Отправьте ещё раз.
404	Неверный секрет, подпись, не совпадающая ни с одним секретом, отключённый вебхук, нет такого воркфлоу, или человек, чей это вебхук, больше не может запускать воркфлоу — агентом с ним больше не делятся, пользователям с доступом больше нельзя запускать его воркфлоу или его аккаунт отключён. На вебхуке, включённом до появления подписи, доставка, подписанная его секретом, получает 404, пока вы один раз не нажмёте Обновить секрет. Когда рабочая интеграция начинает получать 404, сначала проверьте, не был ли обновлён секрет и не отключён ли вебхук.

Параллельность включается по желанию. Как только вебхук включён, прямо под ним в карточке Триггеры воркфлоу появляется Максимум параллельных запусков: это число доставок, которые могут выполняться одновременно. По умолчанию оно равно 1, поэтому у нового воркфлоу параллельности нет вовсе: доставка, пришедшая, когда у человека, чей это вебхук, уже идёт запуск этого воркфлоу, отклоняется с 409, точно так же, как любой другой триггер. Поднимите его, и доставки одного вебхука действительно смогут выполняться одновременно, а не стоять в очереди или отклонять друг друга. Число действует для вебхука каждого человека отдельно: при значении 3 ваши доставки и доставки другого человека получают по три одновременно. Это верхняя граница, а не гарантия даже после повышения: общий для платформы лимит на число одновременно выполняющихся запусков по вебхукам во всех воркфлоу может удерживать любой из них ниже собственной настройки, когда платформа загружена. Когда все слоты заняты, следующие доставки ждут в очереди, а не отклоняются: до 20 ожидающих одновременно на каждый вебхук, каждая — до 40 минут. Обычно ожидание заканчивается намного раньше лимита — как только один из выполняющихся запусков этого человека завершится и освободит слот.

Доставка в очереди всё же может потеряться. Если до истечения 40 минут ни один слот не освободится или воркфлоу перестанет быть готовым к запуску, пока доставка ждёт, — вебхук отключат или обновят его секрет, воркфлоу не пройдёт проверку или на балансе, который оплачивает доставку, закончатся кредиты, — доставка отбрасывается, а не выполняется с опозданием. Она появляется в Истории запусков как прерванный запуск с причиной queue_expired. Очередь, в которой уже 20 доставок, отвечает на новую кодом 429, а не принимает событие, которое некуда положить. То, что вы направляете на URL, должно уметь повторять запрос при 409, 429 или 503; доставку в очереди (202) сразу повторять не нужно — платформа её уже держит. Действительно теряется только доставка, которая позже истекает (queue_expired), и отправить её заново — ваша задача.

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

Параллельные запуски делят внешний мир воркфлоу, и не всегда чисто. Каждый запуск получает собственное рабочее пространство для выполнения кода, собственные MCP-подключения и собственную часть истории разговора, поэтому файлы скриптов или контекст чата одной доставки не могут просочиться в соседнюю. Не изолировано то, что шаг пишет в собственную базу данных агента: такие записи работают по принципу «последняя запись побеждает», поэтому шаг, который читает значение, меняет его и записывает обратно, может потерять обновление, если другая доставка делает то же самое почти одновременно. Если включаете параллельность, проектируйте шаги «прочитать — изменить — записать» с учётом этого. Долговременная память намеренно общая, а не изолирована для каждого запуска: каждый запуск от имени одного и того же человека читает и пишет память этого человека с агентом, и каждый запуск читает собственную память агента, — так то, что узнал запуск по вебхуку, может использовать более поздний запуск по расписанию или чат.

Возобновление прерванного запуска по вебхуку претендует на другой, единственный слот. Помимо описанного выше параллельного пула, у каждого человека есть ещё один слот на каждом воркфлоу, и его используют «Возобновить», «Перезапустить» и все его ручные, плановые и запущенные агентом запуски. Нажмите Возобновить на прерванном запуске по вебхуку, пока выполняется ваш запуск того же воркфлоу по расписанию или вручную, — и получите отказ с 409, даже если в самом пуле вебхука есть место. Чужие запуски никогда не занимают ваш слот.

Вебхук с ошибками продолжает падать. Запуски по вебхуку, завершившиеся ошибкой, попадают в письмо о сбое воркфлоу человека, чей это вебхук, так же как запуски по расписанию с ошибкой, — но вебхук не выключается сам, как расписание. Доставки продолжают приходить и падать, пока вы не исправите воркфлоу или не отключите вебхук, поэтому реагируйте на первое же уведомление о сбое.

Использование тела запроса¶

Всё, что отправляет вызывающая сторона, доступно шагам как {{trigger_payload}} — вставьте это в промпт шага или в любое другое место, куда можно подставить переменную. Шаг получает всё тело как текст JSON с ключами в алфавитном порядке. Плейсхолдер всегда означает всё тело целиком: {{trigger_payload.order_id}} — это не способ достать одно поле, но и не ошибка: в промпт просто попадут эти символы, вместе с фигурными скобками. Чтобы работать с одним полем, пусть шаг извлечёт его, а дальше ссылайтесь на этот шаг как {{<node_id>.output}} или {{<node_id>.output.order_id}} для одного поля его результата. Обычно для этого используют шаг Преобразование: он читает текст JSON и возвращает найденные поля, каждое из которых можно подставить дальше. Шаг Скрипт читает его по-другому: дайте скрипту вход, который заполняется более ранним шагом, и читайте его в коде как inputs['<name>'] — значение приходит готовым объектом Python рядом с кодом. Вставить {{trigger_payload}} в код скрипта не получится — это отклоняется при сохранении, потому что плейсхолдер, написанный в коде, становится частью программы, а не данными, которые она читает.

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

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

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

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

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

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

Живые логи узлов¶

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

Живые логи транслируются по запросу и не сохраняются: они доступны, только пока шаг выполняется (и недолго после), и не хранятся в постоянной истории запуска. Если шаг выводит очень много, в живом просмотре остаются только последние строки.

Шаги внутри параллельной группы пока не транслируют живые логи — если открыть такой шаг, панель будет пустой; это ожидаемо, а не ошибка.

Когда ответ AI-шага не соответствует форме¶

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

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

Всё, что нельзя привести без догадок, остаётся ровно в том виде, в каком пришло, и шаг завершается ошибкой. Для отсутствующего числа, отсутствующего «да/нет» или значения, которое должно быть из фиксированного списка, разумной замены нет, — а если поле можно правдоподобно понять двумя способами, Агент Атом не выбирает ни один из них. Ошибка называет поле, которое не подошло, чтобы было видно, что менять. Шаг, завершившийся такой ошибкой, теперь повторяется автоматически, а не заканчивает запуск при первом промахе — второй проход часто возвращает чистый ответ.

Что было скорректировано¶

В истории запусков шаг, ответ которого пришлось скорректировать, несёт значок Нормализовано со счётчиком — это касается и шага внутри параллельной группы. Наведите на него, чтобы увидеть, какие поля были затронуты. Шагу без значка ничего не понадобилось.

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

Как потребовать, чтобы поле было заполнено¶

Поскольку пустое значение теперь считается присутствующим, пометьте поля, в которых обязательно должно что-то быть:

текст не должен быть пустым → задайте минимальную длину 1
список не должен быть пустым → задайте минимум 1 элемент
значение из фиксированного набора → перечислите допустимые значения

Эти условия проверяются после заполнения, поэтому шаг, который вернул пустое значение в помеченном так поле, всё равно завершается ошибкой и всё равно повторяется — а не завершается тихо с пустым полем.

Исправление и восстановление¶

Когда запуск завершается ошибкой, воркфлоу может попытаться восстановиться сам, а для воркфлоу с ошибками проверки интерфейс предлагает Исправить с помощью AI и Пересобрать.

Самовосстановление запуска, принадлежащего человеку, с которым поделились агентом, исправляет только этот запуск; сам воркфлоу из-за этого никогда не меняется.

Исправление можно также остановить, пока оно идёт. Запуск переходит в состояние «прервано», ошибка по-прежнему показана, а кнопка Исправить с помощью AI тут же, если вы предпочитаете вмешаться сами. Оттуда Продолжить самовосстановление возвращает запуск системе для новой попытки с собственным свежим бюджетом на исправление — как будто ошибка только что произошла. Так продолжить запуск можно не больше двух раз; после этого кнопка остаётся видимой, но неактивной.

Когда прерванный запуск продолжается — после Возобновить, повторного запуска с определённого шага, Продолжить самовосстановление или автоматического прохода самовосстановления, — уже завершённые шаги заново не выполняются: на схеме они подписаны Переиспользовано, в истории запусков отмечены как переиспользовано, и за ними сохраняются время, токены и кредиты того прохода, в котором они выполнялись, а итог запуска по-прежнему учитывает каждый шаг один раз. Повторный запуск с определённого шага для уже завершённого запуска вместо этого начинает новый запуск; переиспользованные им шаги не показывают там ни времени, ни стоимости, потому что этот запуск на них ничего не потратил. А если предыдущий проход был остановлен до того, как его шаги были оценены, переиспользованный шаг сохраняет время и токены, но не кредиты.

Детальное управление запуском в реальном времени — Стоп, Возобновить, Перезапустить, повторный запуск с шага и Продолжить самовосстановление — включается постепенно и может быть ещё недоступно в вашем аккаунте.

Шаг Преобразование или Агент, который получил ответ, оборванный на полпути, — или ответ не той формы, — снова обращается к модели, показывая ей, что пришло и что с этим не так, до трёх раз в одном запуске. Шаг, получивший пригодный ответ со второй попытки, просто продолжает работу, а история запусков показывает его как завершённый. Шаг, у которого и после трёх попыток нет пригодного ответа, останавливает запуск и сообщает об этом, а не передаёт следующему шагу половину ответа.

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

Шаг, ожидающий модель, может также столкнуться со сбоем на стороне AI-сервиса: сервис перестаёт отвечать, соединение с ним обрывается или он перегружен. Шаг Агент (устаревший) тогда сам повторяет запрос после короткой паузы, не больше двух раз, прежде чем завершиться ошибкой; если более поздняя попытка проходит, шаг просто заканчивается чуть позже, в пределах собственного времени шага. Шаг Агент вместо этого сразу останавливается, и самовосстановление запускает его снова после паузы — сам шаг не переписывается из-за сбоя, в котором он не виноват.

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

Воркфлоу, управляющие браузером

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