smolagents: как устроены ИИ-агенты, выполняющие Python

smolagents стоит выбрать, если агенту на Python нужно на ходу сочетать инструменты и вычисления, а вы можете предоставить ему контролируемую среду выполнения кода. Hugging Face предлагает 2 класса агентов — CodeAgent и ToolCallingAgent. Разница в том, как модель задаёт следующее действие: пишет Python или формирует структурированный вызов инструмента. Минимализм библиотеки удобен для решения задач с чёткими границами, но сохранение состояния процессов, права доступа и изоляция по-прежнему остаются вашей ответственностью.

Сверено с актуальной документацией Hugging Face, LangChain и OpenAI 31 октября 2026 года. Рекомендации ниже основаны на сравнении способов составления действий, управления процессами и изоляции выполнения. Это архитектурная оценка, а не результаты тестов производительности.

Как smolagents использует Python для действий агента

smolagents — библиотека Hugging Face с открытым исходным кодом для создания агентов на Python, у которых действием может быть исполняемый код. Агент работает в цикле под управлением модели: выбирает действие, получает результат и решает, что делать дальше. CodeAgent выражает действие на Python, а ToolCallingAgent — через структурированные вызовы инструментов. Оба принимают модель и набор инструментов. Справочник агентов Hugging Face.

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

Это отличается от работы ассистента, который выдаёт готовый файл с кодом для вашей проверки. Здесь сгенерированный код служит способом выполнить следующее действие самого агента.

При выборе полезно сравнить, какой части приложения нужна гибкость:

Последние две строки отражают акценты в документации LangGraph и OpenAI Agents SDK, а не перечисляют возможности, доступные только им. Выбор зависит от того, какую часть приложения вы хотите структурировать средствами фреймворка.

smolagents CodeAgent: модель сама составляет действия

CodeAgent полезен там, где промежуточную работу проще описать на Python, чем свести к фиксированному набору вызовов. Hugging Face относит к его сильным сторонам циклы, условия и сочетание инструментов, одновременно отмечая необходимость обрабатывать синтаксические ошибки, исключения и непредвиденное поведение. Обзор возможностей.

Представим разработчика, который ищет расхождения в складских записях. Инструмент поиска с доступом только на чтение возвращает записи для проверки. Прежде чем решить, какие из них требуют дополнительного запроса, агенту может понадобиться привести названия к единому виду, сгруппировать похожие позиции и просуммировать значения поля. Такие промежуточные операции естественно выражать на Python.

Результат выполнения становится основанием для следующего решения модели. Ошибка в вычислении — это наблюдение, на которое агент может отреагировать, но не гарантия того, что он сумеет её исправить.

ToolCallingAgent: действия в пределах заданного набора

С ToolCallingAgent лучше начинать, если у ваших операций уже есть чётко определённые контракты. Он формирует структурированные вызовы в JSON с именами инструментов и аргументами вместо того, чтобы генерировать действия на Python. Сравнение от Hugging Face.

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

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

Инструменты и модель выбирают независимо

Ограничивайте набор инструментов необходимым и выбирайте модель отдельно. В этом разделении и состоит практическая привлекательность smolagents: можно менять способ рассуждения агента, не переопределяя каждую бизнес-операцию.

Инструмент — это функция с понятным контрактом

Инструмент smolagents оборачивает функцию, добавляя имя, описание, метаданные входных параметров и тип результата. Декоратор @tool подходит для простых функций с аннотациями типов и содержательным docstring. Для более сложного инструмента можно создать подкласс Tool и поместить логику выполнения в forward. Руководство по инструментам.

Для складского помощника лучше предоставить операцию «найти записи в разрешённом каталоге», чем неограниченный доступ к базе данных. Проверку принадлежности данных организации, ограничения запросов и объёма ответа нужно реализовать внутри инструмента. Убедительный промпт этих проверок не заменит.

Источником инструментов может быть и Model Context Protocol, или MCP, — стандартный интерфейс для предоставления инструментов приложениям на базе моделей. Также доступны адаптеры для инструментов LangChain и Hugging Face Spaces. Само по себе повторное использование инструмента не означает, что его реализации можно доверять. При загрузке инструментов из Hub Hugging Face явно требует trust_remote_code=True, поскольку они выполняют сторонний код. Документация по подключению и загрузке инструментов.

Это решение требует проверки кода. Прежде чем открывать агенту доступ к инструменту, изучите его реализацию и зависимости.

Способ подключения модели не определяет песочницу

В актуальном справочнике моделей описано несколько вариантов:

• InferenceClientModel подключается через Hugging Face Inference Providers.
• LiteLLMModel использует слой интеграции с провайдерами LiteLLM.
• TransformersModel запускает модель Transformers локально.
• OpenAIModel подключается к серверу моделей с OpenAI-совместимым интерфейсом.

В обзоре возможностей также описан Ollama для локального инференса. Это варианты подключения моделей, а не обещание, что любая модель будет одинаково хорошо генерировать код или выбирать инструменты.

Разделяйте два вопроса: где работает модель и где выполняется сгенерированный ею Python? Облачная модель может управлять выполнением в Docker. Локальная модель всё равно способна генерировать небезопасные действия. Перенос инференса на собственную машину сам по себе не создаёт границу изоляции кода.

Когда переходите от демонстрации к рабочему решению, указывайте модель явно — это важно для воспроизводимости. Hugging Face предупреждает, что модель по умолчанию у InferenceClientModel может меняться. Настройка модели.

Небольшой пример из документации

Прежде чем добавлять инструменты, разберитесь с путём выполнения на арифметической задаче из документации. В вводном примере Hugging Face агенту с пустым набором инструментов предлагают найти сумму чисел от 1 до 10. Вариант ниже сохраняет эту задачу и добавляет менеджер контекста для Docker из руководства по песочницам. Исходный пример, настройка выполнения в Docker.

1. 1

   Подготовьте окружение

   Руководство по установке требует Python 3.10 или новее и рекомендует виртуальное окружение. Для этого примера Docker также должен быть установлен и запущен. Руководство по установке.

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   Задайте переменную окружения HF_TOKEN, указав токен Hugging Face с правом вызова Inference Providers. InferenceClientModel умеет автоматически считывать эту переменную. Не помещайте токен в скрипт. Как работает аутентификация.

2. 2

   Запустите задачу из документации в Docker

   Сохраните код в файл sum_agent.py:

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   Затем выполните:

   python sum_agent.py

   При выходе из блока менеджер контекста освобождает ресурсы песочницы. Это адаптация документации, а не результат тестового запуска, проведённого для этой статьи.

3. 3

   Проверьте результат и границу изоляции

   Ожидаемый математический ответ — 55, по формуле 10 × 11 ÷ 2. Модель сама выбирает, какой Python сгенерировать, поэтому не стоит ожидать строго одинакового хода выполнения или дословно совпадающих ответов при каждом запуске.

   tools=[] означает, что пользовательские инструменты не переданы. Это не лишает CodeAgent возможности выполнять Python. Именно настройка исполнителя переносит сгенерированный код в Docker.

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

Агентам, выполняющим код, нужна песочница

Считайте сгенерированный Python недоверенным кодом и явно задавайте для него песочницу, прежде чем подавать агенту недоверенные входные данные. Локальный исполнитель по умолчанию — это интерпретатор с ограничениями, а не гарантия изоляции основной системы. Hugging Face указывает среди рисков ошибки модели, промпт-инъекции и злонамеренные запросы. Безопасное выполнение кода.

Локальный интерпретатор выполняет абстрактное синтаксическое дерево Python — разобранную структуру программы — операцию за операцией. Он ограничивает импорт и доступ к подмодулям, а также число операций. Эти меры уменьшают риск, но отдельное руководство по безопасности предупреждает: локальное выполнение всё равно несёт угрозы. Разрешая дополнительный пакет, вы расширяете возможности сгенерированной программы.

Какие песочницы поддерживает Hugging Face

Актуальный API исполнителей поддерживает Blaxel, E2B, Modal и Docker наряду с локальным исполнителем. Имена параметров ниже соответствуют справочнику CodeAgent и справочнику исполнителей.

Выбор провайдера и настройка учётных данных — отдельные шаги. В документации по установке перечислены необязательные зависимости; одной их установки недостаточно, чтобы настроить развёртывание.

Для внутреннего эксперимента Docker может дать конкретную границу изоляции, которую можно изучить. Для сервиса, обрабатывающего недоверенные запросы, среду следует выбирать исходя из требований к изоляции, жизненному циклу и управлению выполнением. Этот инфраструктурный выбор подробнее разобран в сравнении песочниц для кода ИИ-агентов.

Изолировать фрагменты кода — не значит изолировать всего агента

Прежде чем добавлять новых агентов, определите, что именно будет находиться внутри изолированной среды. Hugging Face разделяет запуск в песочнице сгенерированных фрагментов кода и размещение там всей агентной системы. Руководство по безопасности предупреждает, что вариант с изоляцией только фрагментов не поддерживает managed agents — агентов, которых другой агент вызывает как помощников. Перенос всей системы внутрь требует дополнительной настройки и может потребовать передачи учётных данных. Подходы к изоляции.

Это влияет на архитектуру. Если в будущем специализированному агенту понадобится вызывать модель из среды выполнения, исходной схемы «отправить код — получить результат» может оказаться недостаточно. Меняя схему развёртывания, заново проверьте размещение учётных данных и зависимости инструментов.

Для клиентского сервиса заранее определите доступные файлы, сетевые адреса и вызываемые операции. Каждому запуску предоставляйте только тот доступ, который нужен для его задачи. Тайм-аут, отмена и освобождение ресурсов должны быть обычными сценариями выполнения, в том числе когда модель не доводит работу до конца.

Когда минимализм помогает, а когда мешает

Выбирайте фреймворк с учётом самой сложной задачи управления в вашем приложении. Короткий код инициализации удобен, но ещё важнее объём кода, который придётся написать вокруг него.

smolagents и LangGraph: динамические действия или управление состоянием процесса

LangGraph — более подходящая отправная точка, если процесс должен сохранять состояние, приостанавливаться и возобновляться, проходя через явно заданные бизнес-состояния. Это низкоуровневая среда оркестрации процессов с поддержкой состояния, его сохранения и участия человека. Она позволяет сочетать детерминированные шаги с шагами под управлением модели и не требует LangChain. Обзор LangGraph.

Возьмём процесс закупки: он собирает обоснования, ждёт решения руководителя и продолжается после согласования. Главная задача здесь — сохранить состояние процесса и обеспечить допустимый переход. Если именно эти требования определяют продукт, начните с LangGraph.

Цена такого выбора — самостоятельное проектирование процесса: состояний, переходов, сохранения данных и правил повторного выполнения шага. Для закупок эти усилия оправданны. Для помощника с ограниченной исследовательской задачей, который читает данные, вычисляет ответ и завершает работу, такая структура может быть лишней.

Выбирайте smolagents, когда главная неопределённость — какие операции Python решат задачу. Выбирайте LangGraph, когда основной вопрос — как процесс должен безопасно переходить между сохраняемыми состояниями. Это рекомендация по проектированию, а не утверждение, что каждый из фреймворков годится только для одного вида работы.

OpenAI Agents SDK: передача задач, проверки и трассировка

OpenAI Agents SDK лучше подходит в качестве исходного выбора, если основа приложения — координация специализированных агентов и проверки при выполнении. Механизм handoff передаёт ведение диалога другому агенту, а подход agents-as-tools позволяет управляющему агенту сохранить ответственность за ответ. Документация по оркестрации.

В помощнике службы поддержки передача диалога специалисту по оплате может быть более понятной абстракцией, чем универсальный решатель задач на Python. Встроенная трассировка записывает обращения к модели, вызовы инструментов, передачи управления и срабатывания защитных проверок. Guardrails обеспечивают автоматические проверки, а механизмы рассмотрения человеком приостанавливают чувствительные действия до принятия решения. Трассировка, защитные проверки и согласование.

На вашей стороне по-прежнему остаются правила приложения: какие действия требуют согласования, как правильно реализовать инструмент и что делать с прерванной работой. Базовые механизмы SDK не определят эти правила за вас. В документации SDK также описаны варианты агентов с песочницей, поэтому выполнение кода нельзя считать исключительной возможностью smolagents.

Предпочтите smolagents, если вам нужно составлять действия на Python и для задачи достаточно небольшого цикла агента. Выбирайте Agents SDK, когда его механизмы координации и согласования соответствуют вашему приложению. Одной «легковесности» для выбора недостаточно.

Более широкий список вариантов есть в сравнении фреймворков для ИИ-агентов. Если вам нужно готовое агентное приложение для установки, а не библиотека для собственной разработки, начните с обзора ИИ-агентов с открытым исходным кодом.

Какие ожидания от агентов, выполняющих код, завышены

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

Не превращайте возможность сочетать операции в универсальное обещание скорости. Объединение операций может менять ход выполнения, но результат по-прежнему зависит от модели, задачи, поведения инструментов и среды исполнения. Прежде чем выбирать по производительности, проведите измерения на собственной задаче.

Есть и конкретное ограничение, которое стоит понимать: в актуальном API агентов значение max_steps по умолчанию равно 20. Оно ограничивает число шагов агента, а не ресурсы, которые может потребить отдельное действие на Python. API также предоставляет обратные вызовы, управляемых агентов и проверки итогового ответа, поэтому минимализм не следует путать с отсутствием средств контроля. Справочник агентов.

Практический вывод: отдельно задавайте ограничения времени выполнения и ресурсов. Лимит шагов не заменяет правила песочницы, а песочница не гарантирует правильность результата.

Что попробовать на следующей неделе

Начните с задачи, у которой есть чёткие границы, доступ только на чтение и ответ, проверяемый независимо. Разработчик на Python, оценивающий smolagents, может взять выгрузку складских данных с удалённой чувствительной информацией и инструмент поиска с узкими полномочиями, а затем сопоставить найденные агентом расхождения с известными примерами.

Фиксируйте, выбирал ли агент нужные записи, правильно ли использовал инструменты, справлялся ли с ожидаемыми сбоями и останавливался ли в заданных пределах. Сохраняйте детерминированный вариант для сравнения. Если задача всегда проходит по одному пути, реализуйте его обычным кодом: рекомендации самого Hugging Face отдают предпочтение детерминированным функциям везде, где это возможно. Рекомендации по созданию агентов.

Переходите к CodeAgent, когда динамическое составление действий на Python оправдывает дополнительную сложность. Используйте ToolCallingAgent, если достаточно заданного набора инструментов. Отложите миграцию, если текущий процесс уже отвечает требованиям. Вернитесь к выбору фреймворка, когда ключевую роль начнут играть согласования с сохранением состояния или передача задач специализированным агентам.

Установка и совместимость

Как установить smolagents через pip?

Установите основную библиотеку командой pip install smolagents. Добавьте необязательные зависимости, необходимые для ваших инструментов, моделей или среды выполнения. В разобранном примере используется smolagents[docker].

Что использовать вместо HfApiModel в smolagents?

В новом коде ориентируйтесь на интерфейс InferenceClientModel из актуальной документации. Прежде чем копировать импорты из старых примеров, сверяйте их с текущим справочником моделей.

Как запускать smolagents в Docker?

Установите и запустите Docker, установите дополнительные зависимости для Docker и выберите executor_type="docker". Настройте границу изоляции под свою нагрузку: один этот параметр не задаёт полноценную политику безопасности.

Практические заметки о разработке с ИИ — в рассылке.