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

Оркестрация tool-calling AI-агента: SOP, лимиты и audit trail

Оркестрация tool-calling в бизнес-агенте — это не «модель сама вызовет API», а жёсткий SOP: planner решает что делать, executor вызывает только whitelist, а

Обсудить задачу Все статьи кластера
Оркестрация tool-calling AI-агента: SOP, лимиты и audit trail

Оркестрация 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-операций нужен там, где есть необратимые действия.

Кто должен владеть картой инструментов? Тот, кто отвечает за интеграцию с системой, которую трогает инструмент. Разработчик агента карту не редактирует в одностороннем порядке — иначе права и контракты разъезжаются с реальностью.

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

Заявка

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

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

Раисыч

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

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