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

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

Я не даю модели произвольный REST Bitrix. Даю узкий набор tools, проверяю аргументы, логирую кто/что/когда и умею откатить. Ниже — чеклист и таблица рисков, которые закрываю до боя.

Whitelist инструментов: что агенту можно, а что только человеку

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

Tool	Право	Dry-run	Лимит	Кто approve при сомнении
crm.deal.get / contact.get	read	нет	60/мин	—
crm.deal.list (фильтр узкий)	read	нет	20/мин	—
crm.deal.update (whitelist полей)	write	да	10/мин	HITL если stage ∈ WON/LOSE/invoice
crm.timeline.comment.add	write	опционально	30/мин	—
task.create (шаблон)	write	да	10/мин	HITL если assignee ∉ pool
notify.manager	write	нет	5/мин	—
crm.deal.delete	запрещён	—	0	только человек
user.get / произвольный batch	запрещён	—	0	—
сырой call.method(any)	запрещён	—	0	—

Правила whitelist:

1. Поля на запись — только из allowlist (STAGE_ID из разрешённого набора, COMMENTS, UF_* согласованные). Не ASSIGNED_BY_ID без HITL.
2. Scope по сделке — tool принимает deal_id только из текущего диалога/сессии, не «любой id из промпта пользователя».
3. Идемпотентный ключ — client_request_id на write, чтобы ретрай не создал 3 задачи.
4. Секреты — webhook/token живут на сервере tools, не в промпте.

Чеклист перед включением write-tools:

• Нет generic HTTP tool в сторону Bitrix.
• JSON-schema валидирует enum стадий и типы полей.
• Роль сервиса — минимальные права в Bitrix (не admin).
• Отдельный sandbox-портал для тестов agent tools.
• Kill-switch: флаг TOOLS_WRITE_ENABLED=false без редеплоя кода агента.

Dry-run: как проверять действие до irreversible write

Dry-run — не «модель подумала», а тот же tool-путь с dry_run=true: валидация аргументов, расчёт diff, запись в audit без вызова мутации Bitrix.

Когда dry-run обязателен:

Действие	Почему	Что возвращает dry-run
Смена стадии сделки	Легко «закрыть» или откатить воронку	from_stage → to_stage, allowed?
Смена ответственного	Ломает SLA и мотивацию	old/new user, в pool?
Создание задачи с дедлайном	Спам и чужие assignee	payload + warnings
Массовое (N>1) обновление	Один промпт — десять сделок	reject, если N>1 без HITL
Комментарий с ценой/офертой	Юр. и ценовые риски	flagged phrases

Паттерн в коде агента (логика):

1. Модель вызывает deal_update_stage(...).
2. Gateway всегда сначала execute(dry_run=true).
3. Если risk_score высокий или правило HITL — карточку оператору: «разрешить / отклонить / править».
4. Только после OK — dry_run=false с тем же request_id.
5. Ответ модели клиенту после факта или явного «отправил на подтверждение».

Антипаттерн: «сначала записал в CRM, потом спросил». Для стадий и денег — наоборот.

Audit-log: что писать, чтобы разбирать инцидент за минуты

Без audit tool-calling в CRM — чёрный ящик. Лог должен ответить: какая сессия, какой tool, какие аргументы, dry-run или prod, успех/ошибка, кто подтвердил, какой rollback_id.

Минимальные поля события:

Поле	Пример	Зачем
ts	ISO-8601	порядок
trace_id / session_id	uuid	связь с диалогом
agent_version	semver	регрессии
tool	crm.deal.update	фильтр
args_hash + redacted args	stage, deal_id	PII-safe разбор
dry_run	true/false	отделить проверки
result	ok / validation_error / bitrix_error
bitrix_req_id	если есть	сверка с порталом
actor	agent / human-id	HITL
rollback_of / rollback_id	связь отката

Хранение: 90 дней hot (поиск по deal_id), дальше cold. В лог не кладу токены, полные телефоны, тела webhook secrets.

Еженедельный ритуал: 20 случайных write-событий глазами — совпали ли stage с политикой, не было ли обхода dry-run.

Откат ошибочного действия: заранее, не «разберёмся»

Откат проектирую вместе с tool, а не после первого факапа.

Ошибочное действие	Откат	Окно	Кто жмёт
Неверная стадия	update на previous_stage из audit	≤ 24 ч, пока нет связанных счетов	HITL / я
Лишний комментарий в таймлайне	compensating comment «отмена» + флаг; удаление если API позволяет	≤ 2 ч	HITL
Лишняя задача	завершить/отменить по task_id из audit	≤ 24 ч	HITL
Неверный UF-поле	restore previous value из snapshot в audit	≤ 24 ч	HITL
Уведомление менеджеру	нельзя «забрать» — только follow-up clarification	сразу	HITL
Удаление сущности	не даём tool — откат = бэкап портала / поддержка	—	admin

Правила отката:

1. Перед write tool сохраняет snapshot изменяемых полей (before).
2. Успешный write пишет after + rollback_payload.
3. Кнопка «Откатить» в HITL-UI вызывает тот же gateway, не ручной клик в Bitrix «на глаз».
4. Откат тоже пишется в audit как отдельное событие.
5. Если после ошибки уже ушли деньги/договор — rollback = процессный (человек), не silent API.

Таблица рисков до продакшена

Риск	Вероятность без контроля	Импакт	Контроль	Остаточный
Произвольный method Bitrix	высокая	критический	нет generic tool	низкий
Смена стадии WON/LOSE ботом	средняя	высокий	HITL + dry-run	низкий
Запись цены «от себя» в комментарий	средняя	высокий	phrase filter + база знаний	средний
Дубли задач на retry	высокая	средний	idempotency key	низкий
Утечка webhook в промпт/логи	средняя	критический	server-side secrets	низкий
Prompt-injection «удали все сделки»	средняя	критический	whitelist + scope deal_id	низкий
Тихий write без audit	высокая	высокий	mandatory audit middleware	низкий
Откат невозможен	высокая	высокий	snapshot before	средний
Права сервиса = admin	частая ошибка внедрения	критический	least privilege	низкий
Тест на проде	средняя	высокий	sandbox portal	низкий

Go-live чеклист (одним взглядом):

• Whitelist ≤ 10 tools, delete/batch запрещены
• Write только через dry-run → (HITL?) → commit
• Audit 100% tool calls, PII redacted
• Rollback payload на каждый мутирующий tool
• Kill-switch и least-privilege пользователь Bitrix
• 15 red-team промптов (injection, чужой deal_id, mass update) — все blocked

Часто задаваемые вопросы

Можно ли дать агенту полный REST «для гибкости»?
Нет. Гибкость окупается одним ошибочным delete или batch. Гибкость — в добавлении нового tool в whitelist после ревью, не в открытом API.

Dry-run замедляет ответ клиенту?
На read — не нужен. На write клиент либо получает «передаю на подтверждение», либо commit за сотни мс. Цена задержки ниже цены кривой стадии в воронке.

Чем это отличается от «просто n8n + Bitrix»?
В n8n сценарий фиксирован. У LLM-агента путь выбирается на лету — поэтому нужен gateway с политиками. n8n может быть этим gateway, если все вызовы идут через него, а не из промпта напрямую.

Что логировать, если юристы боятся ПДн в audit?
Храните deal_id, contact_id, хэши и redacted args. Полный текст диалога — в контуре с TTL и отдельным доступом, не в общем tool-log.

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

• Оркестрация tool-calling AI-агента: SOP, лимиты и audit trail
• AI + n8n + Bitrix + Telegram: один надёжный контур
• Production AI-контур: очереди, ретраи, идемпотентность и HITL

Нужен безопасный tool-calling контур под Bitrix/CRM — разберём scope на raisovich.ru.

Какие Bitrix-tools агенту запрещены по умолчанию?

Delete сделок, произвольный batch, сырой call.method(any) и generic HTTP к REST — только узкий whitelist с schema и лимитами частоты.

Когда dry-run обязателен перед записью в CRM?

Смена стадии (особенно WON/LOSE/invoice), смена ответственного, создание задачи с чужим assignee и любое массовое обновление — сначала diff в audit, потом commit.

Что должно быть в audit-log tool-calling?

Сессия, tool, аргументы (с redact PII), dry-run или prod, успех/ошибка, кто подтвердил HITL и rollback_id — чтобы инцидент разбирать за минуты.