TNWS AI

Гайд · TNWS AI

Как сделать читающий инструмент smolagents через декоратор @tool

smolagentsPythonQwen#smolagents#Hugging Face#нейросети
5 мин—

Пошаговый @tool в smolagents для чтения тестового справочника: типы, docstring, точный вход, проверка результата и безопасные границы.

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

Актуальный поисковый запрос: «как сделать свой инструмент smolagents для чтения справочника». Дать агенту одну детерминированную операцию чтения статуса по коду и не открывать операции записи. В официальном руководстве декоратор @tool рекомендован для простых функций: библиотека использует имя, аннотации типов и docstring с описанием аргументов как схему инструмента. Наличие функции не доказывает, что модель обязательно вызовет её, поэтому отдельно проверяют сам инструмент и интеграционный прогон агента. Материал сверён 26 сентября 2026 года с официальной документацией Hugging Face smolagents. Документация прямо помечает API экспериментальным, поэтому перед производственным использованием закрепите версию пакета и повторите тесты. Примеры рассчитаны на Python 3.10+; доступ к конкретной модели и провайдеру проверяется в вашем аккаунте, а не предполагается этой инструкцией.

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

  1. Создайте локальный словарь с вымышленными статусами и функцию только для чтения.
  2. Добавьте аннотации входа и выхода, docstring и секцию Args, затем вызовите функцию напрямую.
  3. Передайте инструмент в ToolCallingAgent вместе с явно выбранной моделью и небольшим max_steps.
  4. Сравните ответ со справочником и проверьте неизвестный код; журнал вызова нужен отдельно от красивого финального текста.

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

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

import os
from smolagents import InferenceClientModel, ToolCallingAgent, tool

STATUSES = {"R-7": "в работе"}

@tool
def read_status(code: str) -> str:
    """Читает статус учебной заявки.

    Args:
        code: Полный код заявки вида R-7.
    """
    return STATUSES.get(code, "Запись не найдена")

assert read_status("R-7") == "в работе"
model = InferenceClientModel(model_id=os.environ.get("HF_MODEL_ID", "Qwen/Qwen3-Next-80B-A3B-Thinking"), token=os.getenv("HF_TOKEN"))
agent = ToolCallingAgent(tools=[read_status], model=model, max_steps=3)
print(agent.run("Проверь по справочнику статус R-7. Не угадывай."))

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

Вход инструмента — строка R-7, ожидаемый прямой результат — «в работе». Для R-8 ожидается «Запись не найдена». Вход агента: «Проверь по справочнику статус R-7. Не угадывай». Приёмочный результат обязан соответствовать словарю; формулировка модели может отличаться. Если в трассе нет вызова read_status, совпавшая фраза не считается доказательством корректности.

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

Декоратор превращает обычную функцию в объект инструмента и строит его описание из проверяемых элементов Python. Это делает контракт обозримым, но не добавляет авторизацию и не санитизирует аргументы автоматически. Если коды принадлежат разным клиентам, фильтрация должна происходить внутри доверенного кода по серверному контексту, а не по инструкции модели. Для записи статуса создавайте отдельную операцию с подтверждением и идемпотентностью; не расширяйте учебную функцию скрытым побочным эффектом.

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

Проведите три теста: корректный код, отсутствующий код и строка неправильного формата. Для третьего случая заранее выберите политику — явная ошибка формата или безопасное «не найдено». Не позволяйте модели исправлять идентификатор догадкой. Зафиксируйте версию пакета и идентификатор модели, потому что smolagents помечает API экспериментальным, а поведение модели может меняться независимо от кода инструмента.

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

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

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

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

  1. Прямой вызов возвращает точное значение для R-7 и явное отсутствие для R-8.
  2. Агенту доступен только читающий инструмент, а не функция изменения словаря.
  3. На интеграционном тесте подтверждён фактический вызов с тем же кодом, который указан пользователем.

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

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

  • Не оставляйте функцию без аннотаций и понятного описания аргумента.
  • Не считайте системную инструкцию заменой проверки прав доступа внутри инструмента.
  • Не храните токен Hugging Face в исходнике или тексте промпта.

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

FAQ

Обязателен ли docstring?

Для качественной схемы инструмента он нужен: модель должна понимать назначение и аргументы.

Можно ли вызвать tool напрямую?

Да; прямой вызов полезен для детерминированного модульного теста.

Гарантирует ли агент вызов функции?

Нет, выбор действия делает модель; проверяйте трассу или память запуска.

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

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

Обязателен ли docstring?

Для качественной схемы инструмента он нужен: модель должна понимать назначение и аргументы.

Можно ли вызвать 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 мин 

Подбор

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

Пройти опрос

Комментарии

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