Smolagents: кодовый ИИ-агент за 15 минут

Первые шаги с smolagents: создание первого кодового агента за 15 минут

Введение

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

Если хочется попробовать собрать собственного ИИ-агента, но сложные фреймворки отпугивают, то библиотека smolagents от Hugging Face подойдет идеально. Она простая, но мощная.

После прочтения станет ясно, чем выделяются smolagents, и главное — заработает кодовый агент, получающий актуальные данные из сети. Переходим к практике.

Что такое кодовые агенты

Прежде чем писать код, разберемся с основой. Агент — это LLM с набором инструментов. Задача вроде "узнай погоду в Лондоне" заставляет модель выбрать подходящие инструменты для решения.

Агенты smolagents из библиотеки Hugging Face уникальны своим подходом к размышлениям. В отличие от систем, генерирующих JSON или текст для выбора инструментов, здесь агенты пишут фрагменты Python-кода, чтобы связать инструменты и логику.

Код точен и удобен для описания циклов, условий и обработки данных. Модель не угадывает комбинации — она просто составляет скрипт. Как открытый фреймворк агентов, smolagents легкий, прозрачный и подходит для освоения базовых принципов.

Предварительные требования

Для работы понадобится:

Знания Python: уверенное владение переменными, функциями и pip.
Токен Hugging Face. Используем бесплатный API инференса — зарегистрируйтесь на huggingface.co и найдите его в настройках.
Аккаунт Google опционален. Без локальной установки код запустится в Google Colab.

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

Создадим рабочее пространство. В терминале или свежем Colab-ноутбуке выполните команды.

mkdir demo-project
cd demo-project

Настройте токен безопасности. Лучше хранить его в переменной окружения. В Colab добавьте HF_TOKEN через вкладку секретов слева и читайте через userdata.get('HF_TOKEN').

Первый агент: получатель погоды

Начнем с агента, запрашивающего погоду по названию города. Ему нужен инструмент — функция, которую вызовет LLM. Возьмем бесплатный публичный API wttr.in с данными о погоде в JSON.

Установка и настройка

Создайте виртуальное окружение:

python -m venv env

Оно изолирует зависимости проекта от системы. Активируйте:

Windows:

env\Scripts\activate

macOS/Linux:

source env/bin/activate

В терминале появится (env).

Установите пакеты:

pip install smolagents requests python-dotenv

smolagents — легкий фреймворк Hugging Face для агентов с инструментами; requests — для HTTP-запросов; python-dotenv — загрузка переменных из .env.

Все одним вызовом — это философия smolagents.

Настройка токена API

В корне проекта создайте .env и добавьте:

HF_TOKEN=your_huggingface_token_here

Токен возьмите на huggingface.co/settings/tokens. Структура проекта:

Импорт библиотек

В demo.py вставьте:

import requests
import os
from smolagents import tool, CodeAgent, InferenceClientModel

requests: для запросов к API погоды.
os: безопасное чтение переменных окружения.
smolagents: фреймворк с
- @tool: декоратор для функций-инструментов.
- CodeAgent: агент, пишущий и выполняющий Python.
- InferenceClientModel: связь с хостед-LLM Hugging Face.

Инструмент в smolagents — простая функция. Создадим ее для погоды по городу, добавив в demo.py:

@tool
def get_weather(city: str) -> str:
    """
    Returns the current weather forecast for a specified city.
    Args:
        city: The name of the city to get the weather for.
    """
    # Using wttr.in which is a lovely free weather service
    response = requests.get(f"https://wttr.in/{city}?format=%C+%t")
    if response.status_code == 200:
        # The response is plain text like "Partly cloudy +15°C"
        return f"The weather in {city} is: {response.text.strip()}"
    else:
        return "Sorry, I couldn't fetch the weather data."

Разберем:

Декоратор tool превращает функцию в инструмент для агента.
Docstring описывает назначение и параметры — агент опирается на него.
Внутри — запрос к wttr.in, сервису с текстовыми прогнозами.
Типизация (city: str) подсказывает агенту входные данные.

Так работает вызов инструментов — агент обретает новую возможность.

Настройка LLM

hf_token = os.getenv("HF_TOKEN")
if hf_token is None:
    raise ValueError("Please set the HF_TOKEN environment variable")
model = InferenceClientModel(
    model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
    token=hf_token
)

Агенту нужен "мозг" — LLM для анализа задач. Здесь:

Qwen2.5-Coder-32B-Instruct: мощная кодовая модель на Hugging Face.
HF_TOKEN: токен из .env для защиты.

Создаем агента:

agent = CodeAgent(
    tools=[get_weather],
    model=model,
    add_base_tools=False
)

CodeAgent:

Пишет Python для решения.
Выполняет в песочнице.
Цепляет вызовы инструментов.

Передаем список с get_weather и моделью. add_base_tools=False исключает базовые инструменты для простоты.

Запуск агента

Зададим задачу:

response = agent.run(
    "Can you tell me the weather in Paris and also in Tokyo?"
)
print(response)

При agent.run() агент:

Читает запрос.
Определяет нужные инструменты.
Генерирует код вроде get_weather("Paris") и get_weather("Tokyo").
Выполняет и отдает результат.

Агент Hugging Face в действии: видит get_weather, составляет скрипт в уме (LLM):

Это мысли агента, а не код пользователя.

weather_paris = get_weather(city="Paris")
weather_tokyo = get_weather(city="Tokyo")
final_answer(f"Here is the weather: {weather_paris} and {weather_tokyo}")

Выполняет, получает данные и отвечает дружелюбно. Агент готов работать с веб-API.

Как это работает внутри

Рисунок 5: Внутреннее устройство кодового ИИ-агента

Расширение: добавляем инструменты

Сила агентов — в арсенале. Добавим сохранение отчета в файл:

@tool
def save_to_file(content: str, filename: str = "weather_report.txt") -> str:
    """
    Saves the provided text content to a file.
    Args:
        content: The text content to save.
        filename: The name of the file to save to (default: weather_report.txt).
    """
    with open(filename, "w") as f:
        f.write(content)
    return f"Content successfully saved to {filename}"

# Re-initialize the agent with both tools
agent = CodeAgent(
    tools=[get_weather, save_to_file],
    model=model,
)

agent.run("Get the weather for London and save the report to a file called london_weather.txt")

Теперь агент берет данные и работает с файловой системой. Такая комбинация делает Python-агенты универсальными.

Заключение

За минуты и менее 20 строк основного кода получился рабочий ИИ-агент. smolagents упрощает создание кодовых агентов, пишущих Python для задач.

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

Ссылки и ресурсы

Официальная документация: Документация smolagents Hugging Face.
Исходный код: библиотека открытая, код на GitHub-репозитории smolagents Hugging Face.
Сообщество: форумы Hugging Face для идей других разработчиков.

Первые шаги с smolagents: создайте кодового агента за 15 минут