TNWS AI

Гайд · TNWS AI

Как создать класс Tool в smolagents с явной схемой входа

smolagentsPython#smolagents#Hugging Face#нейросети
4 мин—

Класс Tool в smolagents для поиска учебного артикула: name, description, inputs, output_type, forward, модульная проверка и ошибки схемы.

Задача и применимость

Актуальный поисковый запрос: «как создать кастомный класс Tool в smolagents». Описать переиспользуемый инструмент явным классом, когда одного декоратора недостаточно. Официальный контракт Tool включает name, description, словарь inputs, output_type и метод forward. Это удобно для объекта с конфигурацией или состоянием, но состояние нельзя бездумно делить между пользователями и потоками. Материал сверён 26 сентября 2026 года с официальной документацией Hugging Face smolagents. Документация прямо помечает API экспериментальным, поэтому перед производственным использованием закрепите версию пакета и повторите тесты. Примеры рассчитаны на Python 3.10+; доступ к конкретной модели и провайдеру проверяется в вашем аккаунте, а не предполагается этой инструкцией.

Пошаговая настройка

  1. Унаследуйте класс от Tool и задайте стабильное имя без пробелов.
  2. Опишите единственный строковый аргумент в inputs и строковый результат в output_type.
  3. Реализуйте forward, не добавляя сетевой записи и глобальных изменений.
  4. Создайте экземпляр, протестируйте его напрямую и только затем передайте агенту.

До сетевого запуска установите smolagents, настройте HF_TOKEN или другой документированный способ аутентификации и вынесите идентификатор модели в HF_MODEL_ID. Не вставляйте действующий токен в код, prompt, скриншот или статью. Сначала выполните детерминированную часть примера без модели, затем интеграционный run. Так ошибка схемы или бизнес-логики не смешивается с изменчивым поведением LLM.

Готовый шаблон

from smolagents import Tool

class CatalogLookup(Tool):
    name = "catalog_lookup"
    description = "Возвращает название учебного товара по точному артикулу."
    inputs = {
        "sku": {"type": "string", "description": "Артикул вида A-10"}
    }
    output_type = "string"

    def forward(self, sku: str) -> str:
        data = {"A-10": "тестовый кабель"}
        return data.get(sku, "Артикул не найден")

tool = CatalogLookup()
assert tool("A-10") == "тестовый кабель"
assert tool("A-11") == "Артикул не найден"

Конкретный вход и ожидаемые данные

Вход A-10 должен вернуть «тестовый кабель», а A-11 — «Артикул не найден». Это вымышленный каталог, не цена и не рекомендация товара. После подключения к агенту пользовательский вопрос «Как называется A-10?» считается обработанным корректно только если вызван catalog_lookup с точным A-10, а финальный ответ не добавляет отсутствующие характеристики.

Почему схема работает

Явная схема сообщает модели, какие параметры разрешены, однако она не ограничивает длину строки и не доказывает существование артикула. Проверку формата и прав доступа выполняет forward или нижележащий сервис. Возвращайте компактный сериализуемый результат. Если нужен сложный объект, сверьте поддерживаемые типы output_type в вашей версии и протестируйте реальную передачу; не объявляйте один тип, возвращая другой.

Фактическая проверка и пограничный случай

Для регрессии сохраните снимок публичного контракта: имя, описание, ключи inputs и output_type. Изменение ключа аргумента является несовместимым для промпта и тестов даже тогда, когда Python-класс импортируется. Отдельно имитируйте исключение нижележащего каталога и решите, какой безопасный текст получит агент. Не передавайте внутренний stack trace модели или пользователю.

Протокол воспроизводимости

Для каждого прогона запишите четыре независимых артефакта: точный обезличенный вход, ожидаемое действие, фактическое действие и предметно правильный результат. Не ограничивайтесь снимком финального ответа: он не показывает, был ли вызван нужный инструмент. Повторите опыт не менее трёх раз на одной модели с одинаковыми настройками, затем отдельно после смены версии. В отчёте различайте ошибку маршрутизации, неверный аргумент, сбой Python-кода и неподтверждённую генерацию. Если результат нестабилен, не выбирайте удачный прогон вручную: укажите долю успеха на фиксированном наборе. Настройки температуры и провайдера фиксируйте только если они действительно переданы вашему model-клиенту. Такой протокол позволяет повторить вывод и не превращает единичный удачный ответ в обещание качества.

Синтаксис Python проверяется до публикации через ast.parse. Выполнение с реальной моделью здесь не заявляется: без учётных данных нельзя честно подтвердить доступность конкретного inference provider и поведение модели. Проверяемая часть примера выполняется локально там, где она не требует LLM. Для сетевой части заранее запишите модель, версию smolagents, вход, ожидаемый tool call и предметный эталон, затем сохраните обезличенную трассу.

Критерии приёмки

  1. Экземпляр создаётся без ошибки валидации схемы.
  2. Два прямых вызова дают ожидаемые значения и не меняют каталог.
  3. Имя, описание, вход и выход соответствуют фактическому поведению forward.

Успешное завершение Python-процесса не равно правильному ответу агента. Сверяйте три слоя отдельно: корректность аргументов tool, фактическое наблюдение из доверенного кода и соответствие финальной фразы этому наблюдению. Если хотя бы один слой не прошёл, результат не должен автоматически попадать в CRM, базу знаний или действие с побочным эффектом.

Типичные ошибки и чего не делать

  • Не называйте аргумент в inputs иначе, чем параметр forward.
  • Не используйте расплывчатое description вроде «делает работу».
  • Не помещайте общий изменяемый кэш с данными разных клиентов в один экземпляр без изоляции.

Не увеличивайте число шагов и повторов как универсальное лечение. Сначала найдите первый неверный вызов. Не обещайте одинаковое поведение другой модели или будущей версии библиотеки. Все коды и статусы в примерах вымышлены; заменяя их реальными, соблюдайте авторизацию, минимизацию данных и правила хранения журналов.

FAQ

Когда класс лучше декоратора?

Когда нужны конфигурация, повторное использование или более явный жизненный цикл.

Что вызывает агент?

Метод инструмента через его зарегистрированное имя и схему.

Проверяет ли Tool права?

Нет; авторизацию реализует ваш доверенный код.

Официальные источники

Частые вопросы

Когда класс лучше декоратора?

Когда нужны конфигурация, повторное использование или более явный жизненный цикл.

Что вызывает агент?

Метод инструмента через его зарегистрированное имя и схему.

Проверяет ли Tool права?

Нет; авторизацию реализует ваш доверенный код.

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

ГайдыsmolagentsPython26 сентября 2026

Как ограничить число шагов агента smolagents через max_steps

Настройка max_steps в smolagents на читающем инструменте: что именно ограничивается, тест успешного запроса, исчерпание бюджета и критерии.

4 мин 
ГайдыsmolagentsPython26 сентября 2026

Как проверить финальный ответ smolagents через final_answer_checks

Финальная проверка ответа smolagents на обязательную ссылку на код: сигнатура callback, точный пример, пределы булевой проверки и ошибки.

4 мин 
ГайдыsmolagentsPython26 сентября 2026

Как разобрать ошибку агента smolagents через replay и память

Диагностика smolagents через replay, memory.steps и get_full_steps: что смотреть, как обезличить данные и почему трасса не доказывает качество.

4 мин 

Подбор

Какую нейросеть выбрать

Пройти опрос

Комментарии

Пока тихо. Скажите первое слово