Минималистичный фреймворк для создания AI-агентов за 5 строк кода. SMOLagents от HuggingFace — это легковесная библиотека, которая позволяет агентам писать и выполнять код на Python, вызывать внешние инструменты и работать с моделями из HuggingFace Hub. Никакой магии — только чистый Python и понятная архитектура.
SMOLagents — это легковесный фреймворк от HuggingFace для создания AI-агентов, которые могут писать и выполнять код на Python, вызывать инструменты и взаимодействовать с моделями из HuggingFace Hub. Главная идея: агент — это программа, которая пишет программы. Вместо жёстко заданной цепочки вызовов, агент сам генерирует Python-код для решения задачи и исполняет его в песочнице. Это даёт невероятную гибкость: агент может использовать циклы, условия, переменные — всё, что доступно в Python.
Установка элементарна — один pip-пакет. SMOLagents требует Python 3.10+ и работает с любыми моделями через HuggingFace Hub или LiteLLM. Для локального запуска моделей понадобится transformers и torch — но их можно установить опционально, если не планируется запуск моделей локально.
# Создаём виртуальное окружение python3 -m venv smolagents-env source smolagents-env/bin/activate # Устанавливаем SMOLagents (основной пакет) pip install smolagents # Опционально: поддержка локальных моделей pip install smolagents[local-models] # Опционально: поддержка LiteLLM для OpenAI/Anthropic и др. pip install smolagents[litellm] # Опционально: все зависимости сразу pip install smolagents[all] # Проверка установки python -c "from smolagents import CodeAgent; print('SMOLagents OK ✅')"
CodeAgent — это главный тип агента в SMOLagents. Его ключевая особенность: вместо предопределённого формата вызова инструментов (как function calling в OpenAI), CodeAgent генерирует и выполняет Python-код. Это значит, что агент может комбинировать вызовы инструментов с циклами, условиями, переменными и любыми конструкциями языка — его возможности ограничены только фантазией и песочницей.
Для работы CodeAgent нужны две вещи: модель (HfApiModel для серверных моделей HuggingFace или LiteLLMModel для OpenAI/Anthropic) и список инструментов. По умолчанию агент уже имеет доступ к Python-интерпретатору. В примере ниже мы создаём агента, который решает математическую задачу — и он сам пишет нужный код.
from smolagents import CodeAgent, HfApiModel # Подключаем модель из HuggingFace Hub (серверный инференс) model = HfApiModel( model_id="Qwen/Qwen2.5-Coder-32B-Instruct", provider="together", # HF Inference API, together, fireworks, replicate ) # Создаём CodeAgent — минимальная конфигурация agent = CodeAgent( tools=[], # пока без инструментов model=model, add_base_tools=True, # добавляем Python-интерпретатор ) # Запускаем агента — он сам напишет и выполнит код result = agent.run( "Посчитай сумму всех простых чисел от 1 до 100. " "Выведи результат и список этих чисел." ) print(f"Результат: {result}")
Если CodeAgent — это агент, который пишет код, то ToolCallingAgent работает в более традиционной парадигме: он использует JSON function calling (как в OpenAI API), где LLM возвращает структурированный вызов инструмента, а фреймворк исполняет его. Этот подход лучше подходит для моделей, которые нативно поддерживают function calling, и даёт более предсказуемое поведение.
Выбор между CodeAgent и ToolCallingAgent зависит от задачи и модели. CodeAgent мощнее для сложных многошаговых задач (циклы, условия, агрегация), но требует модель, которая хорошо пишет код. ToolCallingAgent проще и надёжнее для стандартных сценариев, особенно с моделями, оптимизированными под function calling.
from smolagents import ToolCallingAgent, HfApiModel, DuckDuckGoSearchTool # Модель с поддержкой function calling model = HfApiModel( model_id="meta-llama/Llama-3.3-70B-Instruct", provider="together", ) # ToolCallingAgent — работает через JSON function calling agent = ToolCallingAgent( tools=[DuckDuckGoSearchTool()], model=model, max_steps=5, # ограничиваем число шагов ) response = agent.run( "Найди в интернете последние новости о SMOLagents " "и расскажи, что нового в последнем релизе." ) print(f"Ответ: {response}")
Настоящая сила SMOLagents раскрывается, когда вы создаёте собственные инструменты. Декоратор @tool превращает обычную Python-функцию в инструмент, доступный агенту. Достаточно написать функцию с type hints и docstring — SMOLagents автоматически сгенерирует описание, которое LLM увидит при выборе инструмента.
Кастомные инструменты могут делать что угодно: обращаться к базам данных, вызывать API, читать файлы, отправлять email, управлять браузером — любые действия, которые можно выразить в Python. Ниже пример инструмента для работы с файловой системой и API GitHub, которые мы затем передаём агенту.
import json import requests from smolagents import tool, CodeAgent, HfApiModel # Кастомный инструмент 1: чтение файла @tool def read_file(path: str) -> str: """Читает содержимое файла по указанному пути. Используй для чтения логов, конфигов, данных.""" try: with open(path, "r", encoding="utf-8") as f: return f.read() except FileNotFoundError: return f"Файл {path} не найден" # Кастомный инструмент 2: поиск репозиториев на GitHub @tool def search_github_repos(query: str, max_results: int = 5) -> str: """Ищет репозитории на GitHub по ключевым словам. Возвращает топ-N результатов с описанием.""" url = f"https://api.github.com/search/repositories?q={query}&sort=stars&per_page={max_results}" headers = {"Accept": "application/vnd.github.v3+json"} response = requests.get(url, headers=headers, timeout=10) data = response.json() results = [] for repo in data.get("items", []): results.append( f"{repo['full_name']} (⭐{repo['stargazers_count']}): {repo['description']}" ) return "\n".join(results) # Собираем агента с кастомными инструментами model = HfApiModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct", provider="together") agent = CodeAgent( tools=[read_file, search_github_repos], model=model, add_base_tools=True, ) result = agent.run( "Найди на GitHub 3 самых популярных репозитория по AI-агентам " "и расскажи кратко о каждом." ) print(f"{result}")
Одно из главных преимуществ SMOLagents — глубокая интеграция с HuggingFace Hub. Вы можете использовать тысячи моделей: от маленьких локальных (Gemma, Phi, Qwen) до гигантских серверных (Llama-3 70B, Mixtral). SMOLagents поддерживает два основных способа подключения моделей: HfApiModel для серверного инференса (быстро, не требует GPU) и TransformersModel для локального запуска (приватно, без интернета). Также доступен LiteLLMModel — универсальный адаптер для OpenAI, Anthropic, Groq и других провайдеров.
Для локального запуска моделей SMOLagents использует библиотеку transformers с поддержкой квантования (bitsandbytes) — это позволяет запускать модели вроде Llama-3 8B даже на обычном ноутбуке. Важно выбирать модель, соответствующую задаче: для CodeAgent нужны сильные «кодерские» модели (Qwen-Coder, DeepSeek-Coder), для ToolCallingAgent — модели с поддержкой function calling (Llama-3, Command R+).
from smolagents import CodeAgent, HfApiModel, TransformersModel, LiteLLMModel # === Способ 1: HfApiModel — серверный инференс через HF === hf_model = HfApiModel( model_id="Qwen/Qwen2.5-Coder-32B-Instruct", provider="hf-inference", # или together, fireworks, replicate max_tokens=2096, temperature=0.5, ) # === Способ 2: TransformersModel — локальный запуск === local_model = TransformersModel( model_id="HuggingFaceTB/SmolLM2-1.7B-Instruct", device_map="auto", torch_dtype="auto", # load_in_4bit=True, # раскомментировать для квантования ) # === Способ 3: LiteLLMModel — OpenAI, Anthropic, Groq и др. === litellm_model = LiteLLMModel( model_id="gpt-4o", api_key="...", # или переменная окружения OPENAI_API_KEY ) # Рекомендации по моделям для CodeAgent: # - Qwen2.5-Coder-32B — отличный баланс цена/качество # - DeepSeek-Coder-V2 — лучший для сложной кодовой логики # - Llama-3.1-70B — хороший универсал с function calling # Используем любую модель с агентом agent = CodeAgent( tools=[], model=hf_model, # подставьте нужную модель add_base_tools=True, ) agent.run("Сгенерируй Python-скрипт для парсинга CSV-файла и подсчёта среднего значения в колонке 'price'.")
SMOLagents поддерживает создание multi-agent систем, где один агент-менеджер координирует работу нескольких специализированных агентов. Менеджер получает задачу, анализирует её, решает, какому агенту-специалисту её передать, и агрегирует результаты. Это паттерн «менеджер-исполнители» (manager-workers), который отлично масштабируется на сложные сценарии вроде research-агентов или автоматизации бизнес-процессов.
Каждый managed-агент — это самостоятельный CodeAgent или ToolCallingAgent со своими инструментами и инструкциями. Менеджер видит их как инструменты: он «вызывает» нужного специалиста, передавая ему подзадачу. Это позволяет строить настоящие AI-команды, где каждый агент имеет свою зону ответственности.
from smolagents import CodeAgent, HfApiModel, tool, DuckDuckGoSearchTool from smolagents import ManagedAgent model = HfApiModel( model_id="Qwen/Qwen2.5-Coder-32B-Instruct", provider="together", ) # === Агент 1: Веб-исследователь === web_agent = ToolCallingAgent( tools=[DuckDuckGoSearchTool()], model=model, max_steps=5, ) managed_web = ManagedAgent( agent=web_agent, name="web_researcher", description="Ищет информацию в интернете. Используй для поиска фактов, новостей, документации.", ) # === Агент 2: Аналитик данных === @tool def calculate_statistics(numbers: str) -> str: """Вычисляет статистики: среднее, медиану, минимум, максимум. numbers — строка чисел через запятую.""" nums = [float(x.strip()) for x in numbers.split(",")] avg = sum(nums) / len(nums) sorted_nums = sorted(nums) n = len(sorted_nums) median = (sorted_nums[n//2] + sorted_nums[(n-1)//2]) / 2 return f"Среднее: {avg:.2f}, Медиана: {median:.2f}, Мин: {min(nums):.2f}, Макс: {max(nums):.2f}" data_agent = CodeAgent( tools=[calculate_statistics], model=model, add_base_tools=True, ) managed_data = ManagedAgent( agent=data_agent, name="data_analyst", description="Анализирует числовые данные, считает статистики, строит отчёты.", ) # === Агент-менеджер: координирует команду === manager = CodeAgent( tools=[], model=model, managed_agents=[managed_web, managed_data], add_base_tools=True, ) # Менеджер сам решает, кому делегировать подзадачу result = manager.run( "Найди в интернете статистику средней зарплаты Python-разработчиков " "в США за последние 3 года (в тысячах долларов) и проанализируй тренд." ) print(f"📊 Результат работы команды агентов:\n{result}")
SMOLagents включает ещё несколько мощных возможностей, которые делают его production-ready. Во-первых, это безопасная песочница для выполнения кода — можно ограничить доступ к файловой системе, сети и системным вызовам, что критически важно при запуске агентов в продакшне. Во-вторых, встроенная интеграция с Gradio позволяет за пару строк создать веб-интерфейс для вашего агента. В-третьих, полная поддержка стриминга через stream=True — пользователь видит ответ по мере генерации.
Для продакшн-деплоя SMOLagents предоставляет интеграцию с HuggingFace Spaces — вы можете задеплоить агента как веб-приложение одним кликом, используя встроенный Gradio UI. Также поддерживается экспорт в Docker для самостоятельного хостинга на своих серверах или в Kubernetes.
from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool from smolagents.gradio_ui import GradioUI # Создаём агента с ограниченной песочницей agent = CodeAgent( tools=[DuckDuckGoSearchTool()], model=HfApiModel( model_id="Qwen/Qwen2.5-Coder-32B-Instruct", provider="together", ), add_base_tools=True, # Параметры безопасности песочницы: max_print_outputs_length=5000, # ограничение вывода additional_authorized_imports=["json", "csv"], # разрешённые модули ) # === Стриминг: ответ по мере генерации === for step in agent.iter( "Объясни, как работает CodeAgent в SMOLagents, за 3 шага.", stream=True, ): print(f"📍 Шаг {step.step_number}:\n{step}") # === Gradio UI: веб-интерфейс за 3 строки === # Раскомментируйте для запуска: # ui = GradioUI(agent) # ui.launch(server_name="0.0.0.0", server_port=7860)
SMOLagents — это именно то, что обещает название: минималистичный, но мощный фреймворк для создания AI-агентов. Всего за 5 строк кода вы получаете агента, который пишет и выполняет Python-код, вызывает API, ищет в интернете и координирует команду специализированных помощников. Фреймворк органично вписывается в экосистему HuggingFace, давая доступ к тысячам моделей — от крошечных локальных до гигантских серверных. CodeAgent открывает новую парадигму «агент как программист», где гибкость Python-кода заменяет жёсткие цепочки вызовов. Если вы ищете легковесную, понятную и расширяемую основу для своих AI-проектов — SMOLagents определённо заслуживает внимания. Установите, запустите первый пример и убедитесь сами: агенты действительно могут быть smol.