AI Agents fundamentals · Урок 2
Tool use: как описывать инструменты
Хорошие практики описания tools, обработки ошибок и валидации входов/выходов.
Описание инструмента — это API контракт
Когда вы даёте модели tool, она читает его описание как контракт. Качество описания напрямую влияет на качество выбора и аргументов.
Что писать в описании
- Что делает. «Поиск по своему корпусу документов через embedding-БД».
- Когда использовать. «Если пользователь спрашивает о внутренних документах компании».
- Когда НЕ использовать. «Если вопрос про текущие новости — это не наш корпус».
- Аргументы. Имя, тип, описание.
- Что возвращает. Структура ответа.
Обработка ошибок
- Любой tool должен уметь возвращать
status: "error", message: "..."понятным образом. - Агент должен видеть ошибку и иметь шанс попробовать другой путь.
Валидация
- Аргументы tool — через JSON Schema / zod.
- Если модель вернула некорректные аргументы — отдайте ошибку и попросите исправиться, не падайте молча.
Практическое задание
Что сделать после урока
Опишите 3 tool для вашего сценария по структуре «что делает / когда использовать / когда НЕ / аргументы / возвращает».
Готовый промпт
Шаблон под задачу урока
Скопируйте и адаптируйте под свой контекст. Текст в треугольных скобках — то, что нужно заменить.
Опиши tool по контракту: name: <…> description (что делает): <…> when_to_use: <…> when_not_to_use: <…> arguments: <…> returns: <…> errors: <…> Это будет передано LLM как описание tool.
Типичные ошибки
На чём чаще всего спотыкаются
- Описывают tool как «функцию», без «когда использовать».
- Не предусматривают возврат ошибок.
- Не валидируют аргументы.
Лайфхаки
Что работает, но в гайдах не пишут
- «Когда НЕ использовать» — самый ценный пункт описания.
- Возвращайте структурированный JSON, а не свободный текст.
- Логируйте все вызовы tool с аргументами и ответами.
Когда использовать
Любая агентская система.
Когда не использовать
Чат без инструментов.
Официальные источники
Квиз — 2 вопроса
1.Самый ценный пункт описания tool?
2.Что возвращает хорошо спроектированный tool?
Отвечено: 0 из 2