Проще говоря, tool call log - это история всех вызовов инструментов. В ней фиксируют время, пользователя или сессию, выбранный инструмент, аргументы, результат, ошибку, длительность, статус approval, trace id, версию prompt, версию tool schema и решение guardrails. Если агент создал задачу в CRM, лог должен показать: почему он выбрал этот tool, какие поля передал, что вернула CRM и было ли действие выполнено автоматически или через подтверждение.
Хороший журнал не равен простому текстовому логу. Для AI-агентов лучше хранить структурированные записи: JSON с входом, нормализованными аргументами, результатом, кодом ошибки, latency, cost, model, user id, workspace id и ссылкой на trace. Тогда записи можно фильтровать, анализировать, использовать в evals и разбирать спорные кейсы.
Tool call log помогает в трех задачах. Первая - отладка: почему агент вызвал не тот инструмент или передал неверный order_id. Вторая - безопасность: кто разрешил опасное действие, прошел ли вызов через allowlist и approval. Третья - улучшение качества: какие инструменты часто падают, где модель путает аргументы, какие сценарии нужно добавить в тестовый набор.
Важно не превращать журнал в склад чувствительных данных. В логах стоит маскировать токены, API keys, персональные данные, платежные реквизиты и коммерческие секреты. Для части полей полезно хранить hash или redacted-значение, а полный payload держать только в защищенном хранилище с ограниченным сроком жизни.
В production tool call log обычно связывают с trace и audit log. Trace показывает цепочку рассуждения и событий внутри одного запуска, tool call log детально фиксирует каждый вызов инструмента, а audit log нужен для юридически значимых действий: изменение статуса, отправка письма, списание денег, публикация контента или запись в учетную систему.
Примеры
- Агент поддержки вызвал get_order_status с order_id=4821. В tool call log сохранились tool name, аргументы, статус ответа, latency и trace id.
- AI-агент попытался вызвать refund_order, но tool policy потребовала approval. В журнале видно, что действие было заблокировано до подтверждения менеджером.
- В CRM агент создал заметку по звонку. Лог показывает исходные аргументы, id созданной заметки и пользователя, от имени которого выполнено действие.
- Инструмент search_knowledge_base вернул пустой результат. По журналу видно, что модель передала слишком узкий запрос, поэтому сценарий добавили в evals.
- Webhook вернул ошибку 429. Tool call log помогает понять, что проблема не в модели, а в лимите внешнего сервиса.
Где используется
- отладка tool calling в AI-агенте
- разбор спорных действий агента
- контроль опасных операций через approval workflow
- поиск ошибок в аргументах tool schema
- мониторинг latency и ошибок внешних API
- подготовка датасета для tool evals
- аудит действий в CRM, helpdesk, ERP и workflow-системах
- защита от prompt injection и tool poisoning
- расследование инцидентов и восстановление цепочки событий
Связанные термины
Частые вопросы
Что такое tool call log простыми словами?
Это журнал, где записано, какие инструменты вызывал AI-агент, с какими аргументами, что получил в ответ и чем закончился каждый вызов.
Чем tool call log отличается от trace?
Trace показывает общий ход запуска агента: сообщения, шаги, решения, вызовы и ошибки. Tool call log фокусируется именно на вызовах инструментов: аргументах, результате, статусе, времени выполнения и проверках безопасности.
Какие поля стоит логировать при вызове инструмента?
Минимум: trace id, user id или session id, tool name, tool schema version, аргументы, статус, результат или ошибку, latency, время вызова, model, prompt version и решение guardrails или approval.
Можно ли хранить в tool call log персональные данные?
Лучше хранить только то, что нужно для отладки и аудита. Токены, API-ключи, платежные данные и чувствительные поля нужно маскировать, удалять или хранить отдельно с ограниченным доступом и сроком жизни.
Зачем tool call log нужен бизнесу?
Он помогает объяснить действия агента, доказать, что операция прошла по правилам, быстро найти ошибку интеграции и понять, какие сценарии нужно улучшить перед расширением автоматизации.
