Оркестрация tool-calling AI-агента: SOP, лимиты и audit trail
Оркестрация tool-calling в бизнес-агенте — это не «модель сама вызовет API», а жёсткий SOP: planner решает что делать, executor вызывает только whitelist, а
Оркестрация tool-calling в бизнес-агенте — это не «модель сама вызовет API», а жёсткий SOP: planner решает что делать, executor вызывает только whitelist, а каждый шаг пишет audit trail с лимитами и причиной остановки. Я вывожу tool-calling в прод только когда вижу три артефакта: карту инструментов с правами, лимиты на сессию и полный журнал «запрос → tool → результат → решение». Без этого агент либо молчит на полезных шагах, либо жжёт бюджет и CRM в цикле. Смешивать «подумай и сразу дерни API» в одном промпте — путь к непредсказуемым side-effect. Дальше разбираю, как этот SOP выглядит в коде и процессах, что писать в карту инструментов, какие лимиты ставить и что именно фиксировать в журнале, чтобы инцидент разбирался за минуты, а не за день.
Разделение ролей: planner и executor — разные компоненты
Главная ошибка — один промпт, который и рассуждает, и вызывает инструменты. Тогда модель в свободной форме решает, какой API дёрнуть, и вы не можете ни ограничить, ни воспроизвести её решение.
Рабочая схема — два шага:
- Planner. Получает запрос пользователя и контекст, возвращает структурированный план: список шагов, для каждого — имя инструмента из whitelist и аргументы. Ничего не вызывает. Формат — JSON по схеме, не свободный текст.
- Executor. Детерминированный код. Берёт план, проверяет каждый шаг по карте прав и лимитам, вызывает инструмент, пишет результат в журнал. Если шаг не проходит проверку — останавливается и возвращает причину.
Planner может быть LLM, executor — нет. Исполнитель не «думает», он исполняет контракт. Это то, что делает поведение предсказуемым: одинаковый план при одинаковых лимитах даёт одинаковый набор вызовов.
Валидация плана до исполнения — обязательный шаг. Проверяются: имя инструмента в whitelist, аргументы по схеме, типы, обязательные поля, допустимые диапазоны. План, не прошедший валидацию, не исполняется вообще — возвращается на перепланирование с текстом ошибки.
Карта инструментов с правами
Карта — таблица, которая описывает каждый инструмент и границы его применения. Без неё executor не знает, что разрешено, а вы не знаете, что вообще подключено.
Минимальный набор полей на инструмент:
| Поле | Что фиксирует |
|---|---|
| Имя и версия | Уникальный идентификатор, версия контракта |
| Назначение | Одна строка: зачем инструмент агенту |
| Схема аргументов | Типы, обязательность, допустимые значения |
| Права | Read / write, какие сущности затрагивает |
| Обратимость | Можно ли откатить side-effect |
| Лимит вызовов | На сессию и на диалог |
| Владелец | Кто отвечает за инструмент и его контракт |
Правила, которые снимают половину инцидентов:
- Write-инструменты — только с подтверждением для необратимых действий (отправка письма, изменение статуса сделки, списание). Подтверждение — либо явное действие пользователя, либо отдельный шаг плана с проверкой предусловий.
- Никаких «универсальных» инструментов вроде
execute_sqlилиcall_api. Каждый инструмент — узкая операция с понятным контрактом. - Read и write разделены. Инструмент, который читает и пишет в одном вызове, невозможно ограничить лимитом так, чтобы это работало.
- Версионирование контракта. Меняете схему аргументов — поднимаете версию, старый план перестаёт проходить валидацию, а не ломается молча.
Карта хранится в репозитории рядом с кодом executor, а не в промпте. Промпт planner получает из неё только то, что нужно для планирования.
Лимиты на сессию
Лимиты — единственное, что отделяет агента от бесконечного цикла и сожжённого бюджета. Ставятся на уровне executor, не в промпте: просьба «не делай больше десяти вызовов» моделью не исполняется гарантированно.
Что ограничивать:
- Число шагов плана на один запрос пользователя.
- Число вызовов каждого инструмента на сессию и на диалог.
- Число раундов перепланирования — сколько раз план может вернуться с ошибкой, прежде чем агент сдастся.
- Токены и стоимость на сессию — жёсткий потолок, при достижении остановка.
- Время выполнения сессии — таймаут, после которого агент возвращает частичный результат и причину.
- Суммарные write-операции — отдельный счётчик, чтобы агент не перебрал с изменениями в CRM.
При достижении любого лимита агент не «пробует ещё раз», а останавливается и возвращает пользователю понятное сообщение: что сделано, на чём остановились, что нужно от человека. Причина остановки пишется в журнал тем же кодом, что и вызовы.
Лимиты подбираются по факту, а не на глаз: первые две недели в проде смотрите распределение числа шагов и вызовов на сессию, потолок ставите выше 95-го перцентиля, но с запасом не больше двух раз. Оценка: типовой поддержке хватает 5–8 шагов на запрос, но это зависит от сценария — считайте по своим логам.
Audit trail: что писать и зачем
Журнал — не лог приложения для отладки, а доказательство того, что агент действовал в рамках SOP. По нему разбирается инцидент и подтверждается, что side-effect был санкционирован.
На каждый шаг пишется запись с полями:
session_id,step_no, метка времени;- входной запрос пользователя (или его хэш, если есть персональные данные);
- план целиком — до исполнения;
- результат валидации плана;
tool, версия контракта, аргументы вызова;- результат вызова: статус, ключевые поля ответа, код ошибки;
- решение executor: выполнен / отклонён / остановлен по лимиту;
- причина остановки, если была.
Требования к журналу:
- Append-only. Записи не редактируются и не удаляются. Хранение — не меньше срока, за который может всплыть претензия по действиям агента; конкретный срок задаёт ваша политика.
- Связность. По
session_idвосстанавливается вся цепочка «запрос → tool → результат → решение» без пробелов. - Персональные данные — маскируются или хэшируются на входе, полные значения не пишутся.
- Доступ на чтение — у поддержки и у того, кто отвечает за инциденты, без запроса к разработке.
Журнал даёт три практических эффекта: разбор инцидента по фактам, а не по догадкам; доказательство санкционированности write-операций; данные для настройки лимитов и правки карты инструментов.
Как это выглядит в сроках и деньгах
Порядок вывода в прод: сначала карта инструментов и журнал, потом лимиты, потом расширение whitelist. Не наоборот.
Ориентиры студии:
- пилот одного сценария — 60–350 тыс ₽, прототип 10–14 дней;
- базовый агент поддержки — от 50 тыс ₽;
- агент продаж — от 200 тыс ₽;
- сложный контур с несколькими инструментами и подтверждениями — от 500 тыс ₽, полный контур 30–90 дней;
- сопровождение — 15–50 тыс ₽/мес.
Сложный контур — это как раз про оркестрацию: несколько write-инструментов, подтверждения, лимиты, журнал. Если сценарий укладывается в один read-инструмент, полный SOP избыточен — хватит валидации плана и базового журнала.
Чек-лист перед продом
- [ ] Planner и executor — разные компоненты, план валидируется до исполнения.
- [ ] Карта инструментов с правами, схемами, лимитами и владельцами лежит в репозитории.
- [ ] В whitelist нет универсальных инструментов; read и write разделены.
- [ ] Необратимые write-операции требуют подтверждения.
- [ ] Лимиты на шаги, вызовы, перепланирование, токены, время и write-операции заданы в коде.
- [ ] Причина остановки возвращается пользователю и пишется в журнал.
- [ ] Журнал append-only, связный по
session_id, с маскированием персональных данных. - [ ] Доступ к журналу есть у поддержки без обращения к разработке.
- [ ] Есть процедура разбора инцидента: кто смотрит, за какое время, что делает с найденным.
Если коротко
- Tool-calling — это SOP, а не свойство модели: planner планирует, executor исполняет по whitelist, журнал фиксирует каждый шаг.
- Три обязательных артефакта: карта инструментов с правами, лимиты на сессию, полный audit trail.
- Валидация плана до исполнения отсекает некорректные вызовы дешевле, чем разбор side-effect после.
- Лимиты ставятся в коде executor, а не в промпте; при достижении — остановка с причиной, а не повтор.
- Журнал append-only и связный по
session_id— иначе инцидент не разбирается. - Сначала карта и журнал, потом лимиты, потом расширение whitelist.
FAQ
Можно ли обойтись одним промптом с инструкцией «вызывай только эти API»? Нет. Инструкция в промпте не гарантирует соблюдение ограничений: модель может выбрать инструмент вне списка или зациклиться. Ограничения должны быть в коде executor, промпт — только источник плана.
Сколько инструментов держать в whitelist на старте? Минимум, закрывающий сценарий. Каждый лишний инструмент — дополнительная поверхность для ошибки и дополнительная строка в карте прав. Расширяйте по факту, когда базовый сценарий стабилен.
Что делать, если агент упёрся в лимит на полезном шаге? Это сигнал, что лимит подобран неверно или сценарий слишком широкий. Смотрите распределение шагов по журналу, поднимайте потолок выше 95-го перцентиля или дробите сценарий. Не отключайте лимит.
Нужен ли audit trail, если агент только читает данные? Да, но в урезанном виде: план, вызовы, результаты, ошибки. Полный набор с подтверждениями и счётчиком write-операций нужен там, где есть необратимые действия.
Кто должен владеть картой инструментов? Тот, кто отвечает за интеграцию с системой, которую трогает инструмент. Разработчик агента карту не редактирует в одностороннем порядке — иначе права и контракты разъезжаются с реальностью.
Читайте также
- Оркестрация tool calling и аудит AI-агента: этапы, цифры и сроки
- Programmatic tool calling в GPT-5: как сэкономить токены в 2026 году
- Tool calling в Bitrix CRM: whitelist, dry run, аудит и откат — как настроить безопасно
Обсудить задачу
Расскажите, что нужно автоматизировать. Александр Раисович ответит лично и предложит архитектуру решения.