Smolagents — это открытая Python-библиотека от Hugging Face для агентов, которые вместо JSON с именем функции и аргументами сразу пишут исполняемый Python-код. Библиотека вышла в конце 2024 года и к маю 2026 добралась до релиза v1.26.0. Ниже разберем, чем code agents отличаются от обычного tool calling, покажем рабочий пример и сравним smolagents с LangGraph и CrewAI.
В 2026 году code agents — один из немногих подходов к вызову инструментов, где модель не парсит JSON, а сразу пишет и выполняет Python. Smolagents — самая известная реализация этой идеи: библиотека умещается в пару тысяч строк кода, поддерживает песочницы E2B, Docker и Modal, а по данным GitHub на середину июня 2026 года собрала почти 28 тысяч звезд. В статье: как устроены code agents, чем они отличаются от AutoGen и CrewAI, и минимальный пример на несколько строк.
Что такое smolagents и чем он отличается от других агентных фреймворков?
Smolagents — минималистичная библиотека Hugging Face для построения LLM-агентов, где основной тип агента пишет действия в виде Python-кода, а не в JSON.
Библиотеку выпустили в декабре 2024 как замену старым Transformers Agents, которые не прижились еще с 2023 года. К релизу v1.26.0 (29 мая 2026) репозиторий huggingface/smolagents набрал почти 28 000 звезд на GitHub и распространяется под лицензией Apache 2.0 — это открытый код, который можно свободно встраивать в коммерческие проекты.
Автор ролика из подборки для этой статьи, где обозревают запуск библиотеки, сравнивает уровень агентности smolagents с золотой серединой между BabyAGI (слишком много самостоятельности, агент сам решает почти все) и LangChain (слишком жестко прописанные цепочки). Smolagents дает модели свободу писать код, но держит выполнение под контролем через песочницу.
Из коробки библиотека работает с моделями на Hugging Face Hub — а это больше 1,3 миллиона моделей, по данным самой платформы. Через LiteLLM подключаются и проприетарные модели: GPT, Claude, Gemini. Значит, не придется переписывать агента, если завтра захочется сменить провайдера.
Как работают code agents — агенты которые пишут код вместо JSON?
Обычный tool-calling агент генерирует одну JSON-команду за шаг: вызвал функцию, получил результат, решил, что делать дальше. Code agent пишет сразу блок кода с циклом или условием и выполняет несколько действий за один проход.
Разница особенно заметна на многошаговых задачах. Возьмем запрос "найди три последние новости про компанию X и посчитай среднюю длину заголовка". Через JSON-вызовы это минимум два отдельных шага: сначала поиск, потом подсчет в отдельном действии. Code agent решает то же самое одним блоком кода с циклом — модель сама пишет for по результатам поиска и считает длину прямо в коде.
В smolagents такой агент называется CodeAgent. Это агент по умолчанию: он генерирует Python, который вызывает инструменты как обычные функции — search(...), calculate(...) — а не как отдельные структурированные вызовы. Библиотека также поддерживает ToolCallingAgent — классический JSON/текстовый вариант для моделей или сценариев, где выполнение кода избыточно.
Почему код эффективнее JSON для вызова инструментов?
Языковые модели натренированы на огромном объеме кода из открытых репозиториев, поэтому пишут его естественнее, чем формируют жесткий JSON-формат. Код также проще передает объекты между шагами — не нужно сериализовать их в текст и обратно.
С JSON-подходом каждый объект, который агент получил на одном шаге, приходится описывать текстом, чтобы передать на следующий. Пример: агент нашел список из десяти городов с координатами. В JSON-парадигме этот список нужно упаковать в текстовое поле, а на следующем шаге модель заново его разбирает. В коде — это просто переменная, которая живет в памяти интерпретатора между шагами.
Есть и обратная сторона. Сгенерированный код нужно где-то выполнять, а произвольный Python-код от языковой модели — это риск. Поэтому в smolagents исполнение code agent'ов идет через песочницу, а не напрямую в основном процессе.
Что означает "smol" в названии и правда ли библиотека такая компактная?
"Smol" — это акцент на минимализм самой кодовой базы, а не на размер моделей. По собственному описанию проекта, логика агентов укладывается примерно в тысячу строк кода.
Разработчики намеренно не стали делать тяжелый фреймворк с десятками абстракций поверх LLM-вызова. В отличие от более "тяжелых" библиотек с богатой экосистемой плагинов, smolagents можно прочитать и понять целиком за вечер, даже не углубляясь в исходники построчно. Это же облегчает форк или кастомизацию под свою задачу.
Из ролика с подборки для этой статьи: автор отмечает, что размер основного Python-файла агента — около тысячи строк. Для сравнения, полноценные оркестраторы вроде LangGraph держат состояние графа, чекпоинты и маршрутизацию — там объем кода на порядок больше.
Как быстро запустить первого агента на smolagents?
Минимальный агент на smolagents занимает пять-семь строк кода: импорт, инициализация модели, создание CodeAgent и вызов run с задачей.
Установка через pip: pip install 'smolagents[toolkit]'. Дополнительные extras ставятся под конкретные нужды — [docker], [e2b], [litellm], [mcp] для интеграции с MCP-серверами.
Дальше — стандартный сценарий из документации Hugging Face:
from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool
model = InferenceClientModel() # модель через Hugging Face Inference API
agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)
result = agent.run("Сколько сейчас стоит доллар в рублях?")
print(result)По умолчанию, если модель явно не указана, библиотека берет qwen2.5-coder-32b-instruct — эта модель заточена под код и доступна бесплатно через Serverless Inference API. Для более тяжелых задач можно подключить платные модели вроде Llama 3.3 70B, но тут уже нужна Pro-подписка Hugging Face.
Свои инструменты создаются двумя способами: через декоратор @tool над функцией с docstring, где описаны аргументы, или через класс, наследующий Tool. Готовые инструменты можно опубликовать на Hugging Face Hub — и подключать их в других проектах одной строкой.
Как обезопасить выполнение сгенерированного кода?
Код от модели по умолчанию не запускают в основном процессе — для этого в smolagents есть локальный ограниченный интерпретатор и внешние песочницы: E2B, Docker, Modal, Blaxel.
Локальный LocalPythonExecutor разрешает не все импорты подряд — список библиотек нужно явно расширять через additional_authorized_imports. Ограничение бьет по удобству: если агенту нужен, скажем, pandas, а его нет в разрешенных импортах, шаг просто упадет с ошибкой. Зато это защищает от произвольного доступа к файловой системе или сети из сгенерированного кода.
Для продакшена в smolagents рекомендуют внешние песочницы. E2B поднимает облачное изолированное окружение под каждый запуск, Docker — локальный контейнер, Modal и Blaxel — облачные раннеры с собственным биллингом. В версии v1.25.0 в песочничный слой добавили токен-аутентификацию и убрали открытый allow_origin — это снизило риск, что чужой процесс достучится до раннера агента.
| Способ выполнения | Где работает | Когда использовать |
|---|---|---|
| LocalPythonExecutor | В том же процессе, с ограниченными импортами | Прототип, локальные эксперименты |
| Docker | Локальный контейнер | Self-hosted продакшен, полный контроль над окружением |
| E2B | Облачная песочница на запрос | Быстрый старт без своей инфраструктуры |
| Modal / Blaxel | Облачные раннеры с масштабированием | Нагрузка с переменным трафиком |
Smolagents или LangGraph и CrewAI — что выбрать?
Smolagents выигрывает, когда агент — это в основном код и небольшой набор инструментов, без сложного графа состояний. LangGraph и CrewAI лучше подходят, если нужен явный контроль над маршрутизацией между множеством агентов.
LangGraph дает больше контроля через явный граф состояний с чекпоинтами — подробнее об этом в отдельном разборе LangGraph — что это и зачем нужен stateful agent. CrewAI ближе к smolagents по духу мультиагентности, но делает упор на роли и командную работу агентов, а не на код как основной способ действия.
| Фреймворк | Основной подход | Сильная сторона | Когда выбрать |
|---|---|---|---|
| smolagents | Code agents | Минимализм, быстрый старт, песочницы из коробки | Задача решается кодом + несколькими инструментами |
| LangGraph | Граф состояний | Явный контроль маршрутов, чекпоинты | Сложные ветвящиеся сценарии, долгие сессии |
| CrewAI | Роли и команды агентов | Понятная модель "команда специалистов" | Мультиагентные сценарии с разделением ролей |
| AutoGen | Диалог между агентами | Гибкая коммуникация между несколькими LLM | Исследовательские и итеративные задачи |
Для мультиагентных систем в smolagents есть ManagerAgent, который координирует несколько ManagedAgent — каждый со своим набором инструментов. Если задача шире одного фреймворка, стоит посмотреть общий разбор: Multi-agent фреймворки: что выбрать в 2026.
Кому подходит smolagents в 2026 году?
Smolagents подходит разработчикам, которые хотят собрать агента с минимумом абстракций и готовы принять компромисс: выше риск выполнения, зато выше гибкость и естественность кода.
Библиотека особенно уместна там, где задача укладывается в несколько инструментов и код, а не в разветвленный workflow с десятками состояний. Для одношаговых вызовов (спросил — получил ответ) разница между code agent и обычным tool calling почти не ощущается: выигрыш code agents проявляется именно на многошаговых задачах, где нужны циклы, условия и комбинация нескольких инструментов подряд.
Максим: «Я уверен полностью, что языки программирования вообще не нужно изучать. Нейросети обучены на 80+ языках. Нужно погружаться в архитектуру: фронт, бэк, база данных.»
Логика smolagents подтверждает этот подход на практике: модель не нужно учить синтаксису конкретного JSON-протокола, она просто пишет код так, как училась на миллионах примеров. Если вы собираете AI-агента для своего продукта и хотите, чтобы код писала за вас нейросеть, а не наоборот, посмотрите обзор Claude Code — он часто идет в связке с такими фреймворками на этапе разработки самого агента.
FAQ
Что такое smolagents простыми словами?
Это библиотека от Hugging Face, которая позволяет собрать AI-агента за несколько строк кода. Особенность — агент решает задачу, сам написав и выполнив Python-код, а не отправляя структурированный JSON-запрос к функции.
Чем code agent отличается от обычного tool calling агента?
Tool calling агент вызывает по одной функции за шаг и ждет результата. Code agent пишет сразу блок кода с циклами и условиями, который может вызвать несколько инструментов за один проход.
Безопасно ли давать агенту выполнять сгенерированный код?
В локальном режиме риски снижены через ограниченный список разрешенных импортов. Для продакшена рекомендуют внешние песочницы — E2B, Docker, Modal или Blaxel, где код агента изолирован от основной системы.
Какие модели можно использовать со smolagents?
Любые модели с Hugging Face Hub через Inference API, а также проприетарные модели вроде GPT, Claude и Gemini — через интеграцию с LiteLLM.
Нужно ли знать Python, чтобы работать со smolagents?
Базовое понимание Python пригодится для написания собственных инструментов и чтения логов агента. Сам код для решения задачи пишет модель, а не разработчик.
Чем smolagents лучше LangGraph или CrewAI?
Не лучше и не хуже — это разные инструменты под разные задачи. Smolagents выигрывает в задачах, которые укладываются в код и небольшой набор инструментов. LangGraph дает больше контроля на сложных ветвящихся сценариях.
Можно ли использовать smolagents в коммерческом продукте?
Да, библиотека распространяется под лицензией Apache 2.0, которая разрешает коммерческое использование без отчислений разработчикам Hugging Face.
Глоссарий
- Code agent — тип агента, который выражает свои действия в виде исполняемого кода, а не JSON или текста.
- Tool calling agent — классический подход, где модель генерирует структурированный вызов функции, а система сама парсит и исполняет его.
- Песочница (sandbox) — изолированная среда выполнения кода, которая ограничивает доступ агента к файловой системе, сети и памяти основного процесса.
- Inference API — сервис Hugging Face, который позволяет обращаться к моделям на Hub без их локального развертывания.
- MCP (Model Context Protocol) — протокол для подключения агента к внешним инструментам и источникам данных единым стандартом.
Хотите собрать своего агента, но не знаете, с какого фреймворка начать? Загляните в каталог AI-инструментов VibeCoderz — там собраны обзоры IDE и агентных платформ с плюсами и минусами. А если нужна помощь с архитектурой конкретного проекта, запишитесь на консультацию к Максиму.
Обновлено: август 2026.