Содержание
Как создать агента на Hugging Face
Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.
Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 22 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.
Создать агента на Hugging Face проще всего через библиотеку smolagents: она даёт готовый класс CodeAgent, которому передают модель и список инструментов, после чего агент решает задачу циклом «мысль — действие — наблюдение». В документации проекта smolagents описан как открытая Python-библиотека, позволяющая собирать и запускать агентов в несколько строк кода. Минимальный рабочий пример из той же документации: инициализировать модель, создать агент с пустым списком инструментов и вызвать метод run с текстом задачи. Дальше разберём установку, выбор модели, добавление инструментов и проверку результата.
Мы скачали подборку результатов веб-поиска по запросу «Как создать агента на Hugging Face»: текст отдали 7 из 10.
Прямой ответ и границы продукта
Агент на Hugging Face — это программа, в которой вывод языковой модели управляет ходом работы. В блоге проекта smolagents дано определение: агенты — это программы, где выходные данные LLM управляют рабочим процессом. Там же уточняется, что «агентность» лежит на непрерывной шкале: чем больше полномочий вы отдаёте модели, тем сильнее система похожа на агента.
Библиотека smolagents — преемник модуля transformers.agents, который со временем будет выведен из употребления. Это важно для выбора точки входа: новый код логично писать на smolagents.
Границы продукта очерчены в документации. smolagents — экспериментальный API, который может меняться в любое время, а результаты работы агентов варьируются, поскольку меняются сами API и лежащие в основе модели. Это не готовый сервис с гарантированным поведением, а библиотека для сборки.
Что нужно для старта, по документации и блогу проекта:
- Инструменты — список функций, к которым агент имеет доступ.
- Модель — LLM, которая будет движком агента.
- Среда выполнения — локальный Python или песочница.
Модель может быть любой: открытые модели через Inference API Hugging Face, облачные модели OpenAI и Anthropic через интеграцию LiteLLM, локальный запуск через Transformers или Ollama. Такой набор вариантов описан в документации smolagents.
Отдельно стоит держать в голове, что агент нужен не всегда. В блоге проекта прямо сказано: агенты полезны, когда именно LLM должна определять рабочий процесс приложения, но часто это избыточно. Если заранее известный сценарий покрывает все запросы, надёжнее обойтись обычным кодом. Агентная схема выручает там, где жёсткий сценарий слишком часто не подходит.
Курс Hugging Face Agents Course разбирает эту тему подробнее: в модуле про smolagents перечислены типы агентов — кодовые агенты для задач разработки, агенты с вызовом инструментов для модульных рабочих процессов и retrieval-агенты, которые обращаются к базам знаний. Курс также сравнивает smolagents с LlamaIndex и LangGraph, предлагая выбирать фреймворк под требования проекта.
Условия доступа и источник актуальных требований
Актуальные требования живут в документации smolagents и в материалах курса Hugging Face Agents Course — это первоисточники, к которым стоит возвращаться при каждой смене версии. Библиотека помечена как экспериментальная, поэтому требования и имена классов меняются.
В обсуждении под публикацией о smolagents участник сообщает о замене HfApiModel на InferenceClientModel в новых версиях и о поддержке прежнего имени старыми версиями. Актуальный Quickstart уже использует InferenceClientModel. Это типичная ловушка при копировании примеров из старых статей: код выглядит знакомо, но имена классов уже другие.
Установка описана в документации одной командой с набором инструментов по умолчанию:
pip install 'smolagents[toolkit]'
Для отдельных сценариев документация называет дополнительные наборы: smolagents[litellm] для облачных моделей через LiteLLM, smolagents[transformers] для локальных моделей, smolagents[gradio] для веб-интерфейса.
Токен доступа нужен, когда агент обращается к Inference API. В учебном модуле курса описан порядок: получить токен в настройках профиля Hugging Face с разрешением на inference, затем добавить его в переменные окружения дублированного Space. Токен выдаётся в разделе настроек токенов на сайте проекта.
Условия доступа к самому Inference API, лимиты бесплатного уровня и доступность сервиса из конкретного региона задаются на стороне Hugging Face и меняются. Сверяйте их в документации проекта перед запуском.
Порядок действий: минимальный агент
Документация smolagents приводит минимальный пример: инициализация модели, создание агента без инструментов, запуск задачи. Ниже — тот же порядок, разложенный по шагам.
Шаг 1. Установка. Команда pip install 'smolagents[toolkit]' ставит библиотеку и набор инструментов по умолчанию, включая веб-поиск.
Шаг 2. Выбор модели. В документации показаны три варианта: InferenceClientModel() для моделей на Hub через Inference API, LiteLLMModel(model_id="gpt-4") для облачных провайдеров, TransformersModel(model_id="meta-llama/Llama-2-7b-chat-hf") для локального запуска. Конкретную модель подставляйте свою.
Шаг 3. Создание агента. Класс CodeAgent принимает список инструментов и модель. Пустой список инструментов — рабочий старт: агент решит задачу силами кода, который сам напишет.
Шаг 4. Запуск задачи. Получите токен с разрешением inference и передайте его процессу через HF_TOKEN, например в Bash: export HF_TOKEN="ваш_токен". Сохраните минимальный пример из Quickstart в agent.py:
from smolagents import CodeAgent, InferenceClientModel
model = InferenceClientModel()
agent = CodeAgent(tools=[], model=model)
result = agent.run("Calculate the sum of numbers from 1 to 10")
print(result)
Запустите python agent.py и сравните итог с самостоятельным подсчётом суммы. Редакция этот пример не запускала; доступ к выбранной по умолчанию модели зависит от условий Inference API.
Шаг 5. Добавление инструментов. Второй пример из документации добавляет DuckDuckGoSearchTool, после чего агент может искать в интернете. Задача в примере — узнать текущую погоду в Париже.
Шаг 6. Публикация. Документация отмечает интеграцию с Hub: агенты и инструменты можно выкладывать и загружать как Gradio Spaces.
Ключевые параметры класса агента из справочника API стоит знать до первого запуска:
| Параметр | Назначение | Значение по умолчанию |
|---|---|---|
| tools | список инструментов агента | обязательный |
| model | модель, генерирующая действия | обязательный |
| max_steps | максимум шагов на задачу | 20 |
| add_base_tools | добавить базовые инструменты | False |
| verbosity_level | подробность логов | LogLevel.INFO |
| instructions | свои инструкции в системный промпт | нет |
| managed_agents | агенты, которых можно вызывать | нет |
Эти значения приведены в справочнике API smolagents. Параметр max_steps ограничивает цикл: агент наследуется от MultiStepAgent и на каждом шаге делает одну мысль, один вызов инструмента и его выполнение.
Учебный пример и критерии проверки
Соберём упражнение на основе примеров из документации и блога проекта. Задача: агент, который отвечает на вопрос, требующий и вычисления, и внешних данных.
Промпт для постановки задачи агенту:
Реши задачу по шагам. Сначала определи, каких данных не хватает.
Найди недостающие данные доступными инструментами.
Выполни вычисление в коде и покажи промежуточные шаги.
В конце дай один итоговый ответ с обоснованием.
Задача: [ваш вопрос, требующий расчёта и внешних данных]
Что менять под себя: текст задачи в последней строке, набор инструментов в конструкторе агента, модель в InferenceClientModel.
Три вариации той же задачи:
- Поиск и расчёт. Агент ищет числовые данные в веб-поиске и считает по ним результат.
- Работа с файлом. Агент читает загруженный файл, извлекает нужные поля и строит сводку.
- Многошаговый план. Агент разбивает задачу на подзадачи и выполняет их последовательно, показывая шаги.
Критерии самостоятельной проверки, которые читатель применяет сам:
- Агент уложился в лимит шагов и не зациклился.
- Промежуточные шаги видны в логах при выставленном уровне подробности.
- Итоговый ответ содержит числа, полученные из кода.
- При недоступном инструменте агент сообщает об ошибке.
Блог проекта приводит пример посложнее: инструмент для расчёта времени поездки на основе карт, после чего агенту дают задачу спланировать однодневную поездку на велосипеде вокруг Парижа. Этот пример показывает, как кастомный инструмент расширяет возможности агента.
Смежные варианты и выбор по задаче
smolagents предлагает два типа агентов, и выбор между ними определяет поведение системы.
| Критерий | CodeAgent | ToolCallingAgent |
|---|---|---|
| Формат действий | Python-код | JSON или текст |
| Статус | основной тип, по умолчанию | второй поддерживаемый тип |
| Композиция | вложенность функций, циклы, условия | вызовы инструментов через парсер |
| Песочница | локально, Modal, Blaxel, E2B, Docker | по общим правилам агента |
| Когда выбирать | вычисления и сложная логика | сценарии с предпочтением JSON-вызовов |
Данные таблицы взяты из документации smolagents. Кодовые агенты пишут действия на Python, что даёт естественную композицию: вложенность функций, циклы и условия. Для безопасности документация поддерживает выполнение в песочнице через Modal, Blaxel, E2B или Docker.
ToolCallingAgent пишет вызовы инструментов в JSON и опирается на метод get_tool_call, используя возможности вызова инструментов самой LLM. Этот вариант подходит, когда парадигма JSON-вызовов предпочтительнее.
Курс Hugging Face Agents Course добавляет третий класс — retrieval-агенты. Они обращаются к базам знаний через векторные хранилища и реализуют паттерн Retrieval-Augmented Generation, а также поддерживают контекст разговора через память. Такие агенты полезны, когда нужно соединить веб-поиск с собственной базой знаний.
Для интерфейса документация описывает класс GradioUI: он даёт веб-интерфейс в формате чата, поддерживает загрузку файлов и может сбрасывать память агента в начале каждого взаимодействия. Требует установки набора smolagents[gradio].
Инструменты можно брать из разных источников: с любого MCP-сервера, из LangChain, из Hub Space. Свои инструменты создают через класс Tool или декоратор @tool, а в docstring описывают аргументы текстом — этого требует smolagents.
Выбор по задаче выглядит так. Простые вычисления — CodeAgent без инструментов. Задачи с внешними данными — CodeAgent с поисковым инструментом. Работа с собственной базой — retrieval-агент. Сценарий с JSON-вызовами — ToolCallingAgent. Несколько ролей — оркестрация managed_agents. Публикация для других — Gradio Space.
Типичные проблемы и диагностика
Агент останавливается раньше времени. В комментарии под публикацией о smolagents пользователь сообщает о таком поведении модели QWEN 32B: сгенерированный код иногда содержит несколько вызовов final_answer, включая вызов в середине скрипта. Поскольку final_answer сигнализирует о конце выполнения, код после первого вызова не исполняется. Диагностика: смотреть сгенерированный код в логах и проверять, где стоит первый вызов завершения.
Устаревшие имена классов. Примеры из старых материалов используют HfApiModel. В новых версиях smolagents его заменил InferenceClientModel. Диагностика: сверить имя класса со справочником API текущей версии.
Агент зацикливается. Параметр max_steps ограничивает число шагов, по умолчанию это 20. Если задача не решена за лимит, стоит либо упростить задачу, либо добавить нужный инструмент. Диагностика: поднять уровень подробности логов и посмотреть, на каком шаге агент повторяет действия.
Инструмент не вызывается. smolagents ожидает, что все аргументы инструмента описаны в docstring. Пустое или неполное описание приводит к тому, что модель не понимает, как вызывать функцию. Диагностика: проверить docstring и типы аргументов.
Нестабильные результаты. Документация предупреждает: результаты агентов варьируются, поскольку меняются API и модели. Диагностика: фиксировать версию библиотеки и модели, повторять запуск на одной задаче.
Ошибки доступа к модели. Токен нужен для Inference API, а для облачных провайдеров — свой ключ. Диагностика: проверить, что токен добавлен в переменные окружения и имеет разрешение на inference.
Частые вопросы
Что такое Hugging Face Agents Course?
Это учебный курс Hugging Face, посвящённый сборке агентов. В модуле про smolagents разбираются типы агентов, создание инструментов, retrieval-подход и оркестрация нескольких агентов. Курс также сравнивает smolagents с LlamaIndex и LangGraph. Материалы курса доступны на сайте Hugging Face.
Нужен ли платный аккаунт для запуска агента?
Библиотека smolagents устанавливается локально и не требует аккаунта. Аккаунт и токен нужны, когда агент обращается к Inference API Hugging Face или к Hub. Для облачных моделей через LiteLLM потребуется ключ соответствующего провайдера. Условия и лимиты доступа задаются на стороне сервиса.
Чем CodeAgent отличается от ToolCallingAgent?
CodeAgent пишет действия на Python и является основным типом агента в smolagents. ToolCallingAgent пишет вызовы инструментов в JSON и опирается на метод get_tool_call. Первый удобен для вычислений и сложной логики, второй — для сценариев с JSON-вызовами. Оба требуют модель и список инструментов при инициализации.
Можно ли запустить агента на своей машине?
Да, документация описывает локальный запуск через TransformersModel или Ollama. Кодовые агенты по умолчанию выполняются локально, а для изоляции поддерживаются песочницы Modal, Blaxel, E2B и Docker. Локальный запуск снимает зависимость от внешнего API, но требует ресурсов под модель.
Как проверить, что агент работает правильно?
Смотрите логи на выбранном уровне подробности и проверяйте промежуточные шаги. Итоговые числа должны приходить из выполненного кода. Если агент завершается раньше времени, проверьте, где в сгенерированном коде стоит первый вызов final_answer. Повторный запуск на той же задаче покажет стабильность результата.