Детерминированные операторы

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

Зачем их использовать

Любая логика, которую можно записать явно, должна быть записана явно. LLM, который «вычисляет итог» или «форматирует дату», — это анти-паттерн: он медленнее, дороже и может ошибаться.

Практическое правило: если вы можете написать функцию в 5 строк на Python — это оператор, а не agent.

Доступные типы

webhook_action (HTTP-вызов)

Выполняет исходящий HTTP-вызов. Конфигурация:

• URL, метод, заголовки и параметры запроса (с плейсхолдерами из контекста)
• Тело: none, json, form, raw, multipart или mapper (тело, составленное языком маппинга, см. ниже)
• Аутентификация: bearer, basic, api_key_header (пользовательский заголовок) или oauth2 (см. ниже)
• Допустимые HTTP-статусы, максимальная задержка и число повторных попыток (retry_count, 0 по умолчанию, экспоненциальная задержка)
• Выходной ключ, под которым публикуется ответ

database_query / database_manage

database_query читает строки из no-code базы betool или из внешней базы (Postgres, MySQL, MongoDB), зарегистрированной в разделе Приложения → Базы данных → Подключения: фильтр where, полнотекстовый поиск, лимит. database_manage записывает в неё (create или update), при этом содержимое составляется языком маппинга.

file_transform

Преобразует файл. Встроенные преобразователи:

• pdf_extract_text — выделяемый текст PDF (без OCR: отсканированный PDF не даёт текста)
• pdf_split — разбиение PDF
• pdf_to_images — рендеринг страниц PDF в изображения
• xlsx_to_json / xls_to_json — чтение книги Excel в виде строк JSON
• unzip — извлечение архива

file_link (ссылки для скачивания)

Передаёт файлы третьей стороне по ссылке, не помещая их содержимое в поток: для каждого файла из списка в контексте (файлы загрузки, полученные вложения, фотографии инспекции…) узел Ссылки для скачивания создаёт подписанную ссылку для скачивания с ограниченным сроком действия. Следующий шаг формирует то, что получит адресат: ответ входящего webhook, email…

Вывод содержит files (каждая исходная запись, дополненная url и expires_at), file_count, failed, requested и ttl_seconds.

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

compute

Детерминированные вычисления над данными контекста. Встроенные операции:

• column_stats — по каждому столбцу списка строк: сколько из них равны заданному значению (count, total, pct)
• compose_text — составление текста по шаблону из значений потока
• regex_extract — извлечение значений по регулярному выражению
• select_by_substring — разбиение списка на группы по предикатам «содержит / не содержит»
• list_compare — согласованность нескольких списков по ключу-связке
• multi_source_compliance — многомерный аудит соответствия по нескольким источникам
• contact_extract — адреса email и номера телефонов, найденные в тексте, с указанием их источника
• free_slots — свободные слоты, выведенные из занятых периодов
• url_expand — составление URL из баз и путей

Язык маппинга

Это не узел: это язык, который составляет выходной payload из данных контекста (функции $now, $uuid, $concat…). Он используется для тела mapper в webhook_action, для содержимого, записываемого database_manage, и для переменных исходящего вызова phone_call.

data_to_file

Создаёт файл Excel (.xlsx) из данных контекста — списка строк, сетки или нескольких списков (по листу на каждый). Параметры: имя файла (поддерживает шаблоны), имя листа, выбор и порядок столбцов, строка заголовков. Файл сохраняется в хранилище вашей организации, готовый к отправке по email или размещению на Drive.

В целях безопасности ячейки, начинающиеся с =, +, - или @, по умолчанию записываются как текст (никакой внедрённой формулы). Когда ограничения Excel вынуждают обрезать данные, файл помечается как усечённый.

web_fetch

Читает одну или несколько веб-страниц и публикует их читаемый текст в контексте (по умолчанию web.pages). Настройки: число страниц, параллелизм, задержка, максимальный размер. Вердикт robots.txt всегда вычисляется и сообщается; он применяется, только если вы его включили (respect_robots).

Страницы, отображаемые только через JavaScript, не исполняются: читается только отдаваемый HTML. Страница, загрузка которой не удалась, отражается в результате, не вызывая сбоя pipeline.

На стороне агента — два эквивалентных инструмента:

• web_scrape.fetch_page — читает страницу (заголовок, текст, найденные ссылки на email и телефоны).
• web_search.search — веб-поиск через движок SearXNG, размещённый самой платформой: до 5 результатов (заголовок, URL, фрагмент).

Все веб-чтения проходят через одну и ту же защиту anti-SSRF: внутренние, частные адреса и адреса облачных метаданных отклоняются после DNS-разрешения, перенаправления перепроверяются на каждом шаге.

code_step

Когда детерминированная логика выходит за пределы возможностей compute, шаг с кодом выполняет пользовательский код в песочнице Starlark — редактируется напрямую, выполняется сразу после сохранения и ограничен белым списком инструментов (allowlist). См. Шаги с кодом.

Аутентификация и секреты

Операторы, которые взаимодействуют с внешней системой (HTTP, DB), ссылаются на учётную запись, зарегистрированную в организации. Учётные данные никогда не видны внутри самого pipeline — ссылка идёт только на имя учётной записи.

В результате ротация пароля не требует правок ни в одном pipeline.

Когда секрет вводится непосредственно в узле (токен bearer, пароль basic или значение api_key_header у webhook_action, пароль зашифрованного PDF или архива для file_transform), он маскируется сразу после сохранения: редактор, API и инструменты MCP показывают лишь маркер. См. Визуальный редактор, раздел Секреты.

Исходящий OAuth2 (client_credentials)

Для API, требующих токен OAuth2 (корпоративное облако, ERP, сторонние провайдеры), HTTP-оператор поддерживает режим oauth2. Вы регистрируете учётные данные OAuth2 в организации — token_url, client_id, client_secret, scope — а узел ссылается только на нечувствительный идентификатор.

В момент вызова betool получает токен и переиспользует его, пока он остаётся действительным; при истечении срока он лениво обновляется, без фоновой задачи. client_secret никогда не возвращается административным API (раскрывается только индикатор has_secret), а полученный токен размещается как Authorization: Bearer … в исходящем запросе.

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

Идемпотентность

Любой оператор, который производит побочный эффект (HTTP POST, DB INSERT, отправка email), должен быть спроектирован с идемпотентностью на стороне получателя. Рекомендуемая практика:

• Включайте idempotency_key в payload (обычно exchange_id).
• Проверяйте на стороне получателя, был ли ключ уже обработан.

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