Как проектировать инструменты для AI-агентов: рабочие практики и типичные ошибки

Качество AI-агента определяется не только мощностью языковой модели, но и тем, насколько грамотно спроектированы его инструменты. Machine Learning Mastery разобрал, что именно делает tools для агентов эффективными — и какие ошибки превращают умный агент в хаотичный.

Название и описание решают всё Языковая модель не видит исходный код инструмента.

Она видит только его имя, описание и схему параметров — и именно по ним решает, когда и с какими аргументами его вызывать. Пример слабого инструмента: `get_data()` с описанием «получает данные». Пример сильного: `get_user_purchase_history(user_id)` — «возвращает список покупок за последние 90 дней, отсортированных по дате. Используй, когда нужно проанализировать траты или построить персонализацию». Второй вариант объясняет не только что делает инструмент, но и когда его вызывать — это принципиально разные уровни полезности для агента. Имя несёт семантику: `process_file` — слишком широко. `extract_invoice_line_items` — модель сразу понимает контекст и применимость. Хорошая формула: глагол + объект + уточнение.

«Описание инструмента — это промпт для самого инструмента.

Если оно размытое, агент будет галлюцинировать аргументы или вызывать не тот инструмент».

Один инструмент — одна ответственность

Самая частая ошибка — «швейцарский нож»: функция с десятком параметров, которая делает пять разных вещей в зависимости от комбинации флагов. Признаки плохо спроектированного инструмента: Параметр `mode` или `action` с набором строковых значений Более 5–6 параметров в одной функции * В описании есть союз «или» — «ищет контакт или создаёт новый»

• Возвращает разные типы данных в зависимости от входных аргументов * Необязательные параметры, которые кардинально меняют поведение Если инструмент делает несколько вещей — разбей его на отдельные. Агенту проще выбрать из `search_contact` и `create_contact`, чем угадать правильную комбинацию флагов в `manage_contact`. При наборе более 20 инструментов в контексте точность выбора нужного у моделей заметно падает — держи набор компактным.

Параметры и возвращаемые значения

Тип параметра влияет на качество генерации. `string` без описания — источник галлюцинаций. `enum` с явным списком допустимых значений — нет.

Для числовых параметров указывай диапазон и единицы измерения: не `timeout`, а `timeout_seconds: integer, 1–30`. Возвращаемое значение должно быть предсказуемым и компактным: агент добавляет весь вывод инструмента в контекст. Если инструмент вернёт тысячи токенов сырого HTML — это узкое место для всей цепочки вызовов.

Принципы хорошего return value: JSON с фиксированной структурой — модель лучше парсит предсказуемые форматы Ошибки — структурированные данные, а не непойманные исключения Мета-поля: `total_results`, `truncated: true`, `next_cursor` Только то, что нужно агенту для следующего шага — не больше * При ошибке — понятное сообщение с инструкцией по дальнейшим действиям ## Что это значит Инструменты для агентов — не просто обёртки над API. Это интерфейс между языковой моделью и реальным миром, требующий такого же внимания, как публичный API: документация, продуманные типы, тесты в изоляции. Агент не исправит плохо спроектированный инструмент — он будет вызывать его неверно снова и снова.