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 на опасных действиях, полным 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 фиксируете четыре вещи:
- Схема аргументов. Типы, обязательность, допустимые значения.
stage_id— не строка, а enum из стадий конкретной воронки.user_id— не любое число, а ID из списка активных сотрудников. - Роль. Кто может вызывать: агент поддержки, агент продаж, оператор. Роль проверяется на вашей стороне, не на стороне модели.
- Лимит частоты. Например, не больше 20 вызовов
change_stageв час на один диалог и не больше 5assign_responsibleв сутки. Лимит защищает от цикла, в котором модель «чинит» сделку бесконечно. - Уровень риска. Чтение — безопасно. Комментарий и задача — низкий риск. Смена стадии, ответственного, суммы, удаление — высокий риск, только через 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 это не собирается, а бизнес-логику в роботах поддерживать сложнее, чем отдельный сервис.
Читайте также
- Tool calling в Bitrix CRM: whitelist, dry run, аудит и откат — как настроить безопасно
- Оркестрация tool calling и аудит AI-агента: этапы, цифры и сроки
- Programmatic tool calling в GPT-5: как сэкономить токены в 2026 году
Обсудить задачу
Расскажите, что нужно автоматизировать. Александр Раисович ответит лично и предложит архитектуру решения.