TNWS AI

Гайд · TNWS AI

Как выбрать CodeAgent или ToolCallingAgent в smolagents для одной задачи

smolagentsPythonQwen#smolagents#Hugging Face#нейросети
5 мин—

Проверяемое сравнение CodeAgent и ToolCallingAgent: формат действий, исполнение кода, риск, минимальный пример и выбор для чтения справочника.

Задача и применимость

Актуальный поисковый запрос: «как выбрать CodeAgent или ToolCallingAgent smolagents». Выбрать тип агента по механике действия, а не по рекламному впечатлению. В официальной справке CodeAgent формулирует вызовы инструментов как Python-код, а ToolCallingAgent — как JSON-подобные tool calls через механизм модели. Оба требуют model и список tools. Для одного читающего справочника без вычислительной композиции рациональной отправной точкой является ToolCallingAgent. Материал сверён 26 сентября 2026 года с официальной документацией Hugging Face smolagents. Документация прямо помечает API экспериментальным, поэтому перед производственным использованием закрепите версию пакета и повторите тесты. Примеры рассчитаны на Python 3.10+; доступ к конкретной модели и провайдеру проверяется в вашем аккаунте, а не предполагается этой инструкцией.

Пошаговая настройка

  1. Опишите задачу и перечислите строго необходимые операции.
  2. Если достаточно отдельных структурированных вызовов, создайте ToolCallingAgent.
  3. Если действительно нужна композиция данных кодом, оцените CodeAgent и изолированный executor.
  4. Прогоните один и тот же эталон на выбранной модели и сравните корректность, число шагов и поверхность риска.

До сетевого запуска установите smolagents, настройте HF_TOKEN или другой документированный способ аутентификации и вынесите идентификатор модели в HF_MODEL_ID. Не вставляйте действующий токен в код, prompt, скриншот или статью. Сначала выполните детерминированную часть примера без модели, затем интеграционный run. Так ошибка схемы или бизнес-логики не смешивается с изменчивым поведением LLM.

Готовый шаблон

import os
from smolagents import InferenceClientModel, ToolCallingAgent, tool

@tool
def read_label(code: str) -> str:
    """Читает учебную метку.

    Args:
        code: Код записи.
    """
    return {"R-7": "синий"}.get(code, "нет записи")

model = InferenceClientModel(model_id=os.environ.get("HF_MODEL_ID", "Qwen/Qwen3-Next-80B-A3B-Thinking"), token=os.getenv("HF_TOKEN"))
agent = ToolCallingAgent(tools=[read_label], model=model, max_steps=3)
print(agent.run("Назови метку R-7 только по инструменту."))

Конкретный вход и ожидаемые данные

Для запроса о метке R-7 правильное проверяемое значение — «синий». Здесь не требуется арифметика, циклы или обработка таблицы, поэтому JSON-вызов одного инструмента достаточен. Если позже задача станет «собери сто значений и агрегируй их», CodeAgent может быть уместнее, но тогда сгенерированный код нельзя запускать локально над чувствительными ресурсами без оценки угроз.

Почему схема работает

Сравнение опирается на проверяемые различия:

ПараметрToolCallingAgentCodeAgent
Представление действийJSON-подобные tool callsPython-код
Исполнение произвольного кодаНе является основной механикойДа, через executor
Простое чтение одной записиПрямой выборОбычно избыточен
Требование изоляции кодаЗависит от самих toolsКритично для недоверенных задач

Это не рейтинг качества: результат зависит от модели, инструментов и тестов.

Фактическая проверка и пограничный случай

Соберите десять реальных, но обезличенных задач и заранее задайте правильные tool calls. Считайте долю верного выбора инструмента, долю верных аргументов и число шагов. Не смешивайте эти показатели с красотой финальной формулировки. Такая матрица показывает, какой агент подходит именно вашему сценарию, и выявляет, что ошибка часто находится в описании инструмента, а не в классе агента.

Протокол воспроизводимости

Для каждого прогона запишите четыре независимых артефакта: точный обезличенный вход, ожидаемое действие, фактическое действие и предметно правильный результат. Не ограничивайтесь снимком финального ответа: он не показывает, был ли вызван нужный инструмент. Повторите опыт не менее трёх раз на одной модели с одинаковыми настройками, затем отдельно после смены версии. В отчёте различайте ошибку маршрутизации, неверный аргумент, сбой Python-кода и неподтверждённую генерацию. Если результат нестабилен, не выбирайте удачный прогон вручную: укажите долю успеха на фиксированном наборе. Настройки температуры и провайдера фиксируйте только если они действительно переданы вашему model-клиенту. Такой протокол позволяет повторить вывод и не превращает единичный удачный ответ в обещание качества.

Синтаксис Python проверяется до публикации через ast.parse. Выполнение с реальной моделью здесь не заявляется: без учётных данных нельзя честно подтвердить доступность конкретного inference provider и поведение модели. Проверяемая часть примера выполняется локально там, где она не требует LLM. Для сетевой части заранее запишите модель, версию smolagents, вход, ожидаемый tool call и предметный эталон, затем сохраните обезличенную трассу.

Критерии приёмки

  1. Выбор обоснован необходимыми действиями, а не только длиной примера.
  2. Для R-7 подтверждён вызов read_label и значение «синий».
  3. Если используется CodeAgent, явно зафиксированы executor и границы доступа.

Успешное завершение Python-процесса не равно правильному ответу агента. Сверяйте три слоя отдельно: корректность аргументов tool, фактическое наблюдение из доверенного кода и соответствие финальной фразы этому наблюдению. Если хотя бы один слой не прошёл, результат не должен автоматически попадать в CRM, базу знаний или действие с побочным эффектом.

Типичные ошибки и чего не делать

  • Не выбирайте CodeAgent только потому, что он может выполнять больше действий.
  • Не называйте JSON tool calls автоматически безопасными: сам tool может удалять данные.
  • Не переносите метрики одной модели на другую без нового прогона.

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

FAQ

Какой агент проще для API-функций?

Обычно ToolCallingAgent, если модель поддерживает вызовы инструментов.

Когда нужен CodeAgent?

Когда задача выигрывает от композиции и вычислений в коде.

Какой точнее?

Универсального ответа нет; точность измеряют на вашем наборе задач.

Официальные источники

Частые вопросы

Какой агент проще для API-функций?

Обычно ToolCallingAgent, если модель поддерживает вызовы инструментов.

Когда нужен CodeAgent?

Когда задача выигрывает от композиции и вычислений в коде.

Какой точнее?

Универсального ответа нет; точность измеряют на вашем наборе задач.

Читайте также

ГайдыsmolagentsPython26 сентября 2026

Как ограничить число шагов агента smolagents через max_steps

Настройка max_steps в smolagents на читающем инструменте: что именно ограничивается, тест успешного запроса, исчерпание бюджета и критерии.

4 мин 
ГайдыsmolagentsPython26 сентября 2026

Как проверить финальный ответ smolagents через final_answer_checks

Финальная проверка ответа smolagents на обязательную ссылку на код: сигнатура callback, точный пример, пределы булевой проверки и ошибки.

4 мин 
ГайдыsmolagentsPython26 сентября 2026

Как разобрать ошибку агента smolagents через replay и память

Диагностика smolagents через replay, memory.steps и get_full_steps: что смотреть, как обезличить данные и почему трасса не доказывает качество.

4 мин 

Подбор

Какую нейросеть выбрать

Пройти опрос

Комментарии

Пока тихо. Скажите первое слово