Tool result — это ответ, который приложение возвращает модели после вызова инструмента. Например, агент вызвал CRM API, поиск по базе знаний, расчет доставки или создание задачи, а tool result сообщает: успешно ли выполнено действие, какие данные получены и что можно делать дальше.
Хороший tool result не должен быть просто “сырым JSON на тысячу строк”. Модели нужен компактный и понятный результат: status, key fields, id объекта, найденные источники, ограничения, ошибки, next steps и краткое summary. Так агент меньше путается и реже использует лишние или чувствительные данные.
Tool result важен для безопасности. Backend должен убрать секреты, персональные данные сверх необходимости, внутренние поля, токены, stack traces и лишние права. Если tool завершился ошибкой, результат должен описать ошибку так, чтобы агент мог корректно продолжить: повторить, уточнить данные, отказаться или передать человеку.
В агентных системах tool result обычно сохраняют в trace. Это помогает потом понять, почему агент принял решение, какой API ответил, какие данные были доступны модели и где возникла ошибка.
Примеры
- CRM tool возвращает status=success, deal_id, current_stage и next_activity, а не всю карточку сделки с внутренними комментариями.
- Поиск по базе знаний возвращает top chunks, titles, source URLs и short_summary, чтобы модель могла ответить с цитатами.
- Инструмент отправки письма возвращает draft_id и status=draft_created, но не отправляет письмо без approval.
- API доставки возвращает status=delayed, tracking_number, last_checkpoint и recommendation=create_ticket.
- Если tool call упал, tool result возвращает error_code, safe_message и retry_allowed=false, чтобы агент не повторял опасное действие бесконечно.
Где используется
- Передать модели результат API-вызова в структурированном виде.
- Сократить большой JSON до полезного summary и ключевых полей.
- Отделить успешный результат, ошибку, предупреждение и handoff.
- Скрыть секреты и лишние персональные данные перед возвратом модели.
- Сделать поведение агента после tool call предсказуемым.
- Логировать результаты инструментов в trace для отладки и аудита.
- Писать evals и тесты на корректную обработку ошибок tools.
Связанные термины
Частые вопросы
Что такое tool result простыми словами?
Это ответ инструмента после вызова. Агент попросил инструмент что-то сделать или найти, а tool result сообщает, что получилось, какие данные важны и есть ли ошибка.
Почему нельзя возвращать модели весь сырой JSON?
Большой сырой JSON занимает контекст, содержит шум и может включать лишние или чувствительные поля. Лучше вернуть компактный структурированный результат с нужными данными.
Что должно быть в хорошем tool result?
Обычно нужны status, summary, ключевые поля, id объектов, источники, ошибки, ограничения, next_step и признак, нужно ли подтверждение человека.
Чем tool result отличается от tool schema?
Tool schema описывает, какие аргументы инструмент принимает. Tool result описывает, что инструмент вернул после выполнения.
Как безопасно возвращать ошибки инструмента?
Нужно дать агенту понятное безопасное сообщение, error_code и действие: повторить, уточнить данные, отказаться или передать человеку. Stack trace, токены и секреты возвращать нельзя.
