SmolAgents — минималистичный open-source фреймворк для разработки ИИ-агентов, созданный командой Hugging Face. Позволяет запускать и интегрировать агентов всего за несколько строк на Python. Работает с большинством языковых моделей (LLM) разного типа, включая Hugging Face Hub, OpenAI и Anthropic.
Основные отличия SmolAgents
- Минимум абстракций, компактный код (~1000 строк в ядре).
- Простая интеграция различных LLM и инструментов.
- Основной режим — кодовые агенты: все действия выполняются через генерацию и исполнение Python-кода.
- Поддержка классических агентов вызова инструментов (JSON-формат вызова), для сценариев, где выполнение кода не требуется.
- Встроенная безопасность и возможность песочницы для изоляции кода.
Быстрый старт: запуск агента
Для создания минимального агента нужны:
- Аргумент
model— выбранная LLM. - Аргумент
tools— список инструментов.
Пример:
from smolagents import CodeAgent, HfApiModel
model_id = "meta-llama/Llama-3.3-70B-Instruct"
model = HfApiModel(model_id=model_id)
agent = CodeAgent(tools=[], model=model, add_base_tools=True)
agent.run("Выведи 118-ое число Фибоначчи.")
Инструменты SmolAgents
Инструмент (Tool) — функция или класс, которую агент может вызывать для решения задач, например, веб-поиск, работа с файлами или API.
SmolAgents поддерживает:
- Встроенные инструменты (например, DuckDuckGoSearchTool, PythonInterpreter).
- Кастомные инструменты (на основе декоратора @tool или через наследование класса Tool).
- Импорт инструментов из Hugging Face Hub.
- Интеграцию с коллекциями LangChain и Gradio Spaces.
Пример кастомного инструмента:
from smolagents import tool
@tool
def model_download_tool(task: str) -> str:
"""
Возвращает самый популярный модельный чекпоинт для задачи.
Args:
task: название задачи (text-classification, text-to-video и др.)
"""
from huggingface_hub import list_models
return next(iter(list_models(filter=task, sort="downloads", direction=-1))).id
И добавление в агента:
agent = CodeAgent(tools=[model_download_tool], model=HfApiModel())
Практические советы по созданию хороших агентов
- Объединяйте похожую логику в одном инструменте — это снижает количество вызовов LLM, уменьшает стоимость и вероятность ошибок.
- Формулируйте задачу для LLM максимально конкретно.
- Протоколируйте ошибки и важные детали работы инструментов (метод
forward). - Используйте как можно больше детерминированных функций — это ускоряет работу системы.
Безопасное исполнение кода
SmolAgents запускает сгенерированный код в специализированном безопасном интерпретаторе Python с ограниченным списком разрешённых импортов и количеством операций.
Для максимальной изоляции можно использовать E2B: код выполняется в удалённой песочнице, не влияя на вашу систему. Подключение через параметр use_e2b_executor=True. Поддерживается добавление зависимостей через additional_authorized_imports.
Пример:
agent = CodeAgent(
tools=[VisitWebpageTool()],
model=HfApiModel(),
additional_authorized_imports=["requests", "markdownify"],
use_e2b_executor=True
)
Многоагентные системы
Фреймворк позволяет объединять несколько агентов для решения одной задачи, что удобно при комплексных сценариях.
Создание управляющего агента через ManagedAgent:
from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool, ManagedAgent
model = HfApiModel()
web_agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)
managed_web_agent = ManagedAgent(
agent=web_agent,
name="web_search",
description="Выполняет поисковые запросы в интернете."
)
manager_agent = CodeAgent(
tools=[],
model=model,
managed_agents=[managed_web_agent]
)
manager_agent.run("Кто руководитель Hugging Face?")
Каждый агент может иметь отдельный набор инструментов и память, что даёт гибкость для распределённых задач.
Пример: текст в SQL
SmolAgents можно использовать для систем text-to-SQL, где агент сам генерирует и проверяет SQL-запросы, устраняя типичные ошибки “голых” text-to-SQL пайплайнов:
- Создаётся инструмент-обёртка вокруг SQLAlchemy.
- Описание схемы таблицы добавляется в документирование инструмента.
- LLM может критически анализировать результат и изменять стратегию запроса.
SmolAgents — это лёгкий и гибкий фреймворк, который подойдет как для простых ассистентов, так и для сложных распределённых систем. Кодовые агенты позволяют упростить управление логикой, а инструменты дают огромную свободу интеграции с реальным миром. Фреймворк активно развивается, предлагая приоритет безопасности и совместимости с разными моделями LLM.
