smolagents

<!-- Uncomment when CircleCI is set up
<a href="https://circleci.com/gh/huggingface/accelerate"><img alt="Build" src="https://img.shields.io/circleci/build/github/huggingface/transformers/master"></a>
-->
<a href="https://github.com/huggingface/smolagents/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/huggingface/smolagents.svg?color=blue"></a>
<a href="https://huggingface.co/docs/smolagents"><img alt="Documentation" src="https://img.shields.io/website/http/huggingface.co/docs/smolagents/index.html.svg?down_color=red&down_message=offline&up_message=online"></a>
<a href="https://github.com/huggingface/smolagents/releases"><img alt="GitHub release" src="https://img.shields.io/github/release/huggingface/smolagents.svg"></a>
<a href="https://github.com/huggingface/smolagents/blob/main/CODE_OF_CONDUCT.md"><img alt="Contributor Covenant" src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg"></a>
<a href="https://deepwiki.com/huggingface/smolagents"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>

Агенты, которые думают кодом!

smolagents — это библиотека, которая позволяет вам запускать мощных агентов в несколько строк кода. Она предлагает:

✨ Простота: логика для агентов помещается примерно в 1000 строк кода (см. agents.py). Мы сохранили абстракции в минимальном виде поверх чистого кода!

🧑‍💻 Первоклассная поддержка Кодовых Агентов. Наш CodeAgent записывает свои действия в виде кода (в отличие от "использования агентов для написания кода"). Для обеспечения безопасности мы поддерживаем выполнение в изолированных окружениях через Blaxel, E2B, Modal или Docker.

🤗 Интеграция с Хабом: вы можете обмениваться инструментами или агентами с/на Хаб для мгновенного обмена самыми эффективными агентами!

🌐 Независимость от модели: smolagents поддерживает любую LLM. Это может быть локальная модель transformers или ollama, одна из множества провайдеров на Хабе или любая модель от OpenAI, Anthropic и многих других через нашу интеграцию с LiteLLM.

👁️ Независимость от модальности: Агенты поддерживают текстовые, визуальные, видео и даже аудио входы! Смотрите это руководство для работы с изображениями.

🛠️ Независимость от инструментов: вы можете использовать инструменты из любого MCP-сервера, из LangChain, вы даже можете использовать Hub Space как инструмент.

Полная документация доступна здесь.

[!NOTE] Ознакомьтесь с нашим постом в блоге о запуске, чтобы узнать больше о smolagents!

Быстрая демонстрация

Сначала установите пакет со стандартным набором инструментов:

pip install "smolagents[toolkit]"

Затем определите своего агента, предоставьте ему необходимые инструменты и запустите его!

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)

agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

https://github.com/user-attachments/assets/84b149b4-246c-40c9-a48d-ba013b08e600

Вы даже можете поделиться своим агентом на Хабе, в виде репозитория Space:

agent.push_to_hub("m-ric/my_agent")

# agent.from_hub("m-ric/my_agent") чтобы загрузить агента с Хаба

Наша библиотека независима от LLM: вы можете заменить пример выше на любой inference provider.

InferenceClientModel, шлюз для всех inference providers, поддерживаемых на HF

from smolagents import InferenceClientModel

model = InferenceClientModel(
  model_id="deepseek-ai/DeepSeek-R1",
  provider="together",
)

LiteLLM для доступа к 100+ LLM

from smolagents import LiteLLMModel

model = LiteLLMModel(
  model_id="anthropic/claude-4-sonnet-latest",
  temperature=0.2,
  api_key=os.environ["ANTHROPIC_API_KEY"]
)

Серверы, совместимые с OpenAI: Together AI

import os
from smolagents import OpenAIModel

model = OpenAIModel(
  model_id="deepseek-ai/DeepSeek-R1",
  api_base="https://api.together.xyz/v1/", # Оставьте пустым для запросов к серверам OpenAI.
  api_key=os.environ["TOGETHER_API_KEY"], # Замените на API-ключ целевого сервера.
)

Серверы, совместимые с OpenAI: OpenRouter

import os
from smolagents import OpenAIModel

model = OpenAIModel(
  model_id="openai/gpt-4o",
  api_base="https://openrouter.ai/api/v1", # Оставьте пустым для запросов к серверам OpenAI.
  api_key=os.environ["OPENROUTER_API_KEY"], # Замените на API-ключ целевого сервера.
)

Локальная модель transformers

from smolagents import TransformersModel

model = TransformersModel(
  model_id="Qwen/Qwen3-Next-80B-A3B-Thinking",
  max_new_tokens=4096,
  device_map="auto"
)

Модели Azure

import os
from smolagents import AzureOpenAIModel

model = AzureOpenAIModel(
  model_id = os.environ.get("AZURE_OPENAI_MODEL"),
  azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
  api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
  api_version=os.environ.get("OPENAI_API_VERSION")    
)

Модели Amazon Bedrock

import os
from smolagents import AmazonBedrockModel

model = AmazonBedrockModel(
  model_id = os.environ.get("AMAZON_BEDROCK_MODEL_ID") 
)

CLI

Вы можете запускать агентов из CLI с помощью двух команд: smolagent и webagent.

smolagent — это универсальная команда для запуска многошагового CodeAgent, который можно оснастить различными инструментами.

# Запуск с прямым запросом и опциями
smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7."  --model-type "InferenceClientModel" --model-id "Qwen/Qwen3-Next-80B-A3B-Thinking" --imports pandas numpy --tools web_search

# Запуск в интерактивном режиме (запускает мастер настройки, если запрос не указан)
smolagent

Интерактивный режим проведет вас через: - Выбор типа агента (CodeAgent против ToolCallingAgent) - Выбор инструментов из доступного набора - Конфигурацию модели (тип, ID, настройки API) - Дополнительные опции, такие как дополнительные импорты - Ввод запроса задачи

Тем временем webagent — это специальный агент для веб-сёрфинга, использующий helium (подробнее здесь).

Например:

webagent "go to xyz.com/men, get to sale section, click the first clothing item you see. Get the product details, and the price, return them. note that I'm shopping from France" --model-type "LiteLLMModel" --model-id "gpt-5"

Как работают Кодовые Агенты?

Наш CodeAgent работает в основном как классические ReAct-агенты — за исключением того, что движок LLM записывает свои действия в виде фрагментов кода Python.

flowchart TB
    Task[Задача пользователя]
    Memory[память агента]
    Generate[Генерация из agent.model]
    Execute[Выполнение кода - Вызовы инструментов записаны как функции]
    Answer[Возврат аргумента, переданного в 'final_answer']

    Task -->|Добавить задачу в память агента| Memory

    subgraph ReAct[Цикл ReAct]
        Memory -->|Память в виде сообщений чата| Generate
        Generate -->|Разбор вывода для извлечения действия с кодом| Execute
        Execute -->|Нет вызова инструмента 'final_answer' => Сохранить журналы выполнения в памяти и продолжать| Memory
    end

    Execute -->|Вызов инструмента 'final_answer'| Answer

    %% Styling
    classDef default fill:#d4b702,stroke:#8b7701,color:#ffffff
    classDef io fill:#4a5568,stroke:#2d3748,color:#ffffff

    class Task,Answer io

Действия теперь представляют собой фрагменты кода Python. Следовательно, вызовы инструментов будут выполняться как вызовы функций Python. Например, вот как агент может выполнить веб-поиск по нескольким сайтам в одном действии:

requests_to_search = ["gulf of mexico america", "greenland denmark", "tariffs"]
for request in requests_to_search:
    print(f"Here are the search results for {request}:", web_search(request))

Запись действий в виде фрагментов кода, как показано, работает лучше, чем текущая отраслевая практика, при которой LLM выводит словарь инструментов, которые он хочет вызвать: использует на 30% меньше шагов (а значит, на 30% меньше вызовов LLM) и достигает более высокой производительности на сложных benchmarks. Перейдите к нашему общему введению в агентов, чтобы узнать об этом больше.

Поскольку выполнение кода может серьезно повлиять на безопасность (произвольное выполнение кода!), вам следует запускать код агента в песочнице. Мы поддерживаем несколько вариантов: - E2B, Blaxel, Modal — управляемые облачные песочницы, простые в настройке - Docker — самостоятельный контейнерный изолятор

Встроенный LocalPythonExecutor не является песочницей безопасности. Он применяет некоторые ограничения, но может быть обойден и не должен использоваться как граница безопасности.

Наряду с CodeAgent, мы также предоставляем стандартный ToolCallingAgent, который записывает действия в виде JSON/текстовых блоков. Вы можете выбрать тот стиль, который лучше всего подходит для вашего варианта использования.

Насколько "smol" эта библиотека?

Мы стремились сохранить абстракции в строго минимальном виде: основной код в agents.py имеет менее 1000 строк кода. Тем не менее, мы реализуем несколько типов агентов: CodeAgent записывает свои действия в виде фрагментов кода Python, а более классический ToolCallingAgent использует встроенные методы вызова инструментов. У нас также есть иерархии с несколькими агентами, импорт из наборов инструментов, удалённое выполнение кода, модели зрения...

Кстати, зачем вообще использовать фрамворк? Ну, потому что большая часть этого контекста нетривиальна. Например, кодовый агент должен поддерживать единый формат кода во всей своей системной подсказке, анализаторе, выполнении. Поэтому наш фрамворк берет на себя эту сложность за вас. Но, конечно, мы по-прежнему поощряем вас копаться в исходном коде и использовать только те куски, которые вам нужны, в ущерб всему остальному!

Насколько сильны открытые модели для агентных рабочих процессов?

Мы создали экземпляры CodeAgent с некоторыми ведущими моделями и сравнили их на этом benchmark, который собирает вопросы из нескольких различных benchmarks, чтобы предложить разнообразное сочетание задач.

Найдите код benchmarking здесь для получения дополнительной информации об агентной конфигурации, использованной, и увидьте сравнение использования кодовых агентов LLM с обычными (спойлер: кодовые агенты работают лучше).

Это сравнение показывает, что открытые модели теперь могут конкурировать с лучшими закрытыми моделями!

Безопасность

Безопасность является критически важным аспектом при работе с агентами, выполняющими код. Убедитесь, что вы используете один из вариантов выполнения в песочнице, которые обеспечивают изоляцию от недоверенного кода.

Предупреждение: LocalPythonExecutor предоставляет только меры смягчения последствий и не является границей безопасности. Не используйте его для запуска недоверенного кода.

Для политики безопасности, сообщений об уязвимостях и дополнительной информации о безопасном выполнении агентов, пожалуйста, ознакомьтесь с нашей Политикой безопасности).

Участие

Мы приглашаем всех к участию, начните с нашего руководства по участию.

Цитирование smolagents

Если вы используете smolagents в своей публикации, пожалуйста, процитируйте его, используя следующую запись BibTeX.

@Misc{smolagents,
  title =        {`smolagents`: smol библиотека для создания отличных агентных систем.},
  author =       {Aymeric Roucher and Albert Villanova del Moral and Thomas Wolf and Leandro von Werra and Erik Kaunismäki},
  howpublished = {\url{https://github.com/huggingface/smolagents}},
  year =         {2025}
}