Блог студии Раисыча AI-агенты · автоматизация
Обсудить задачу
ИИ-агенты для продаж 7 мин чтения 14 September 2026

Tool-calling AI-агента в Bitrix/CRM: whitelist, dry-run и откат

Tool-calling AI-агента в Bitrix/CRM безопасен только с whitelist инструментов, обязательным dry-run на опасных действиях, полным audit-log и заранее…

Обсудить задачу Все статьи кластера
Tool-calling AI-агента в Bitrix/CRM: whitelist, dry-run и откат

Tool-calling AI-агента в Bitrix/CRM безопасен только с whitelist инструментов, обязательным dry-run на опасных действиях, полным audit-log и заранее описанным откатом ошибочной операции — иначе агент «успешно» портит сделки и статусы. Я не даю модели произвольный REST Bitrix. Даю узкий набор tools, проверяю аргументы, логирую кто/что/когда и умею откатить. Ниже — чеклист и таблица рисков, которые закрываю до боя. Каждый tool — отдельная функция с схемой аргументов, ролью и лимитом частоты. Всё, чего нет в списке, для модели не существует.

Дальше разбираю, как этот принцип выглядит в коде и процессах: что именно попадает в whitelist, как устроен dry-run, что писать в audit-log и как строить откат так, чтобы он работал не в теории, а в момент, когда агент уже испортил стадию сделки.

Whitelist: список инструментов вместо REST

Модель не должна знать про crm.deal.update, crm.lead.add и остальные методы REST Bitrix24. Она видит только те функции, которые вы ей описали. Всё остальное для неё не существует — не «запрещено», а именно отсутствует в списке доступных вызовов.

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

Минимальный набор для агента поддержки или продаж в Bitrix обычно такой:

  • get_deal(id) — чтение сделки, только поля из белого списка.
  • get_contact(id) — чтение контакта.
  • search_deals(filters) — поиск с жёстко ограниченным набором фильтров.
  • add_timeline_comment(deal_id, text) — комментарий в таймлайн.
  • change_stage(deal_id, stage_id) — смена стадии, только на опасных действиях идёт через dry-run.
  • create_task(responsible_id, title, deadline) — задача сотруднику.
  • assign_responsible(deal_id, user_id) — смена ответственного, тоже опасное действие.

Для каждого tool фиксируете четыре вещи:

  1. Схема аргументов. Типы, обязательность, допустимые значения. stage_id — не строка, а enum из стадий конкретной воронки. user_id — не любое число, а ID из списка активных сотрудников.
  2. Роль. Кто может вызывать: агент поддержки, агент продаж, оператор. Роль проверяется на вашей стороне, не на стороне модели.
  3. Лимит частоты. Например, не больше 20 вызовов change_stage в час на один диалог и не больше 5 assign_responsible в сутки. Лимит защищает от цикла, в котором модель «чинит» сделку бесконечно.
  4. Уровень риска. Чтение — безопасно. Комментарий и задача — низкий риск. Смена стадии, ответственного, суммы, удаление — высокий риск, только через dry-run.

Валидация аргументов — отдельный слой между моделью и API. Модель может вернуть stage_id: "WON" вместо числового ID, может перепутать deal_id и contact_id, может передать дату в свободном формате. Всё это отсекается до вызова REST: не прошло по схеме — возвращаете модели ошибку валидации, а не выполняете операцию.

Dry-run на опасных действиях

Dry-run — это режим, в котором tool не меняет данные, а возвращает модели и в audit-log то, что она собирается сделать. Модель получает ответ вида «будет выполнено: смена стадии сделки 12345 с NEW на PREPARATION, ответственный не меняется» и должна подтвердить намерение либо скорректировать аргументы.

Что обязательно идёт через dry-run:

  • смена стадии сделки;
  • смена ответственного;
  • изменение суммы сделки;
  • закрытие сделки успехом или провалом;
  • массовые операции (любая операция над списком, а не над одной записью);
  • создание сущностей от имени сотрудника (задача, комментарий с упоминанием).

Механика простая: у tool есть флаг dry_run, по умолчанию true для опасных операций. Агент сначала вызывает функцию с dry_run: true, получает план, сверяет его с задачей пользователя, затем вызывает ту же функцию с dry_run: false. Если между двумя вызовами аргументы изменились — план считается недействительным, нужен новый dry-run.

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

Audit-log: кто, что, когда и с каким результатом

Лог пишется вашим слоем-обёрткой, а не Bitrix. Каждый вызов tool — запись с полями:

Поле Что содержит
timestamp Время вызова с точностью до секунды, часовой пояс фиксирован
trace_id ID диалога или запуска агента, связывает цепочку вызовов
tool Имя функции из whitelist
arguments Аргументы после валидации, как они ушли в API
dry_run Был ли это план или реальное выполнение
result Код ответа, ID изменённой сущности, текст ошибки
actor Кто инициировал: пользователь, агент, оператор
before / after Снимок изменяемых полей до и после

Поля before/after — то, что превращает лог из отчётности в инструмент отката. Без снимка состояния откатывать нечего. Храните лог не меньше срока жизни сделки в воронке; на практике — от 90 дней, для крупных сделок дольше.

Лог нужен не только для разбора инцидентов. По нему видно, какие tools модель вызывает чаще всего и где ошибается: если 30% вызовов change_stage отбиваются валидацией, проблема в описании функции или в промпте, а не в модели.

Откат: план до запуска, а не после инцидента

Откат проектируется вместе с tool, а не пишется, когда агент уже наворотил. Для каждой опасной операции заранее описан обратный сценарий:

  • Смена стадии — обратный вызов change_stage со старым значением из before. Работает, если после ошибки сделку не тронули другие процессы.
  • Смена ответственного — обратное присвоение прежнего user_id.
  • Комментарий в таймлайн — не удаляется, а помечается: добавляется запись «отменить предыдущий комментарий агента, ошибочно». Удаление из таймлайна в Bitrix — плохая практика, история должна оставаться.
  • Созданная задача — закрывается с пометкой «создана ошибочно» либо переназначается.
  • Изменение суммы — обратная запись старого значения, но только если после ошибки сумму не меняли вручную.

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

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

Чек-лист перед запуском в бой

  • [ ] Список tools зафиксирован, каждый — отдельная функция с узкой бизнес-операцией.
  • [ ] У каждого tool описана JSON-схема аргументов с enum для статусов и ID.
  • [ ] Валидация аргументов стоит между моделью и REST, ошибки возвращаются модели, а не в API.
  • [ ] Для каждой роли определён свой набор доступных tools.
  • [ ] На каждый tool задан лимит частоты вызовов.
  • [ ] Опасные операции по умолчанию идут с dry_run: true.
  • [ ] Для операций высокого риска есть подтверждение человеком.
  • [ ] Audit-log пишет before/after, trace_id и dry_run.
  • [ ] Для каждой опасной операции описан обратный сценарий и проверка «не изменилось ли с момента ошибки».
  • [ ] Первый этап — только чтение и низкорисковые действия, расширение прав после накопления лога.

Сроки и бюджет

Пилот одного сценария с whitelist, dry-run и логом — 60–350 тыс ₽, прототип 10–14 дней. Базовый агент поддержки с чтением и комментариями в таймлайн — от 50 тыс ₽. Агент продаж со сменой стадий и ответственных — от 200 тыс ₽. Полный контур с откатом, подтверждениями и разграничением ролей — от 500 тыс ₽, срок 30–90 дней. Сопровождение — 15–50 тыс ₽/мес.

Если коротко

  • Модель не получает произвольный REST Bitrix — только узкий whitelist функций.
  • Один tool — одна бизнес-операция, со схемой аргументов, ролью и лимитом частоты.
  • Опасные действия идут через dry-run, высокорисковые — ещё и через подтверждение человеком.
  • Audit-log пишет before/after — без этого откат невозможен.
  • Откат проектируется до запуска и проверяет, не изменилась ли сущность после ошибки.
  • Начинайте с чтения и низкорисковых действий, расширяйте права по логу.

FAQ

Можно ли дать агенту доступ ко всему REST Bitrix и ограничиться промптом? Нет. Промпт — не механизм безопасности: модель может проигнорировать инструкцию, а API выполнит вызов. Ограничение должно быть в коде — в списке доступных функций и валидации аргументов.

Чем dry-run отличается от подтверждения человеком? Dry-run — это план, который модель сверяет сама и показывает в лог. Подтверждение человеком — внешняя проверка для операций высокого риска. Первое дешевле и работает всегда, второе медленнее, но закрывает дорогие ошибки.

Что делать, если после ошибочного действия сделку уже правил менеджер? Автоматический откат в этом случае не выполняется: он затрёт правки. Инцидент разбирается вручную по audit-log, решение принимает ответственный за воронку.

Сколько хранить audit-log? Не меньше срока жизни сделки в воронке, на практике от 90 дней. Для крупных сделок — дольше, потому что разбор может понадобиться через месяцы.

Обязательно ли писать свой слой-обёртку или можно обойтись средствами Bitrix? Свой слой нужен: именно он держит whitelist, валидацию, dry-run и лог с before/after. Средствами Bitrix это не собирается, а бизнес-логику в роботах поддерживать сложнее, чем отдельный сервис.

Читайте также

Заявка

Обсудить задачу

Расскажите, что нужно автоматизировать. Александр Раисович ответит лично и предложит архитектуру решения.

Раисыч

Основатель Студии Раисыча. Проектирую ИИ-контуры для продаж, поддержки и документов — с критериями приёмки и журналом.

Написать в Telegram →
Обсудить задачу