Как оценить библиотеку для ИИ-агентов: методика с открытым бенчмарком на Hugging Face

Почему выбор библиотеки для агентов превратился в лотерею

Открою секрет: 90% репозиториев с пометкой "AI Agent Framework" — это переупакованный langchain с парой кастомных тулов. Звезды на GitHub накручиваются, документация пестрит красивыми схемами, но когда ты пытаешься натравить такого агента на real-world задачу — он падает с RateLimitError или выдает бессвязный бред.

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

В июне 2026 года мы решили покончить с этой неопределенностью и выложили на Hugging Face открытый бенчмарк AgentEval (прямая ссылка в разделе Hugging Face Spaces). Методика простая: берем 20 задач из реальных сценариев (поиск информации, генерация кода, работа с файлами, мультиагентная координация), замеряем success rate, latency и cost. Результаты — в открытой таблице.

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

Что мы измеряем и почему это честнее звезд на GitHub

Бенчмарк AgentEval состоит из 20 юнит-тестов, каждый из которых имитирует поведение реального пользователя:

• Task 1-5 — простые вопросы с известным ответом (например, «Какая погода в Нью-Йорке 12 июля 2026?»). Проверяем, что агент умеет вызывать API.
• Task 6-10 — многокомпонентные задачи (написать пост в блог на тему X, найти 3 цитаты из книг Y). Тут нужен инструмент поиска — вспомните наш разбор поиска с латентностью 700 мс.
• Task 11-15 — задачи с памятью: агент должен помнить контекст предыдущих действий. Мы взяли за основу подход из ICM.
• Task 16-20 — мультиагентная координация: два агента должны обменяться данными и прийти к общему решению. Если библиотека не умеет в роутинг сообщений — мимо.

Каждый тест прогоняется 5 раз с разными сидами. Метрики:

Мы не просто гоняем агентов — мы проверяем, как библиотека справляется с ошибками. Типичная ситуация: упал парсинг JSON от LLM, библиотека должна перезапросить. Если она просто передает SyntaxError наверх — это кандидат на вылет.

Пошаговый план: как прогнать любую библиотеку через AgentEval

1 Установите бенчмарк

Склонируйте репозиторий и установите зависимости:

git clone https://github.com/huggingface/agent-eval-benchmark.git
cd agent-eval-benchmark
pip install -r requirements.txt  # includes transformers>=4.50.0, torch, datasets

Теперь у вас есть папка benchmark/ с файлом tasks.py (все 20 задач), evaluator.py (логика оценки) и шаблоном адаптера adapters/base.py.

2 Напишите адаптер для вашей библиотеки

Адаптер — это класс с двумя методами: setup() и run(task_description: str) -> dict. Пример для библиотеки на основе transformers:

from transformers import pipeline, Tool
from benchmark.adapters.base import BaseAgentAdapter

class MyAdapter(BaseAgentAdapter):
    def setup(self):
        # Загружаем модель с поддержкой tool-use (например, Qwen2.5-72B-Instruct)
        self.agent = pipeline(
            "text-generation",
            model="Qwen/Qwen2.5-72B-Instruct",
            device_map="auto",
            tools=[Tool.from_function(self.my_search_api)]
        )
    
    def run(self, task: str) -> dict:
        # Форматируем промпт, запускаем генерацию, возвращаем результат
        result = self.agent(task, max_new_tokens=1024)
        return {"output": result[0]["generated_text"][-1]["content"], "latency": ...}

Обратите внимание: мы используем нативный tool-use из transformers — это сильно упрощает интеграцию. Если ваша библиотека не поддерживает этот стандарт, придется написать прослойку для конвертации тулов. В ClawBench это сделано через Selenium — у нас универсальнее.

3 Запустите тесты

python run_benchmark.py --adapter my_adapter --tasks 1..20 --trials 5 --output results.json

По умолчанию бенчмарк использует LLM-бэкенд через HfApi (Inference Endpoints). Если хотите локально — укажите --local-model.

4 Интерпретируйте результаты

После прогона вы получите JSON с полями:

{
  "adapter": "my_adapter",
  "results": {
    "overall_success_rate": 0.78,
    "avg_latency": 12.4,
    "avg_cost": 0.032,
    "stability": 0.05,
    "per_task": {
      "task_1": {"success": true, "latency": 8.2},
      ...
    }
  }
}

Теперь сравните с эталонными значениями из таблицы на Hugging Face Spaces. Если success rate ниже 0.7 — скорее всего, библиотека плохо обрабатывает ошибки или у нее кривая система тулов.

Типичные ошибки, которые гарантированно обнулят результат

Прогнав через AgentEval 14 популярных фреймворков (LangChain, CrewAI, AutoGen, pi agent, Swarms, smolagents, etc.), мы собрали «черный список» антипаттернов.

• Игнорирование timeout. Задача на поиск информации должна укладываться в 30 секунд. Если ваш агент уходит в бесконечный цикл ретраев — тест падает. В статье про бенчмаркинг pi agent мы разбирали, как правильный таймаут увеличил success rate на 20%.
• Сырой вывод LLM без парсинга. Агент выдает «Я бы посоветовал...» вместо JSON. Если в библиотеке нет механизма структурирования ответа (например, OutputParser в LangChain), считайте, что вы теряете 40% успешных кейсов.
• Память через глобальные переменные. В мультиагентных тестах это приводит к race condition. Нужен правильный менеджмент контекста — как в ICM.
• Жесткая привязка к одной LLM. Если код хардкодит OpenAI — вы не сможете запустить его локально. Бенчмарк проверяет и transformers модели. Хорошая библиотека абстрагирует провайдера.

Как улучшить свой агент по результатам бенчмарка

Допустим, вы прогнали свою библиотеку и получили success rate 0.65. Что дальше?

1. Посмотрите на per-task метрики. Если падают тесты 11-15 (память) — добавьте семантическое ранжирование контекста. Техника из гибридного поиска по книгам отлично ложится на этот сценарий.
2. Оптимизируйте тулы. Замените requests.get на асинхронный клиент с кэшированием — latency упадет в 2-3 раза. В нашем гайде по сжатию латентности мы показывали, как добиться 700 мс.
3. Добавьте failover. Если LLM возвращает ошибку парсинга, попросите ее перегенерировать ответ с другим промптом. Простая ретрай-логика поднимает success rate до 0.85.

Кстати, именно так мы доработали pi agent в версии 2.1 — он теперь использует агентную схему с планировщиком, как описано в архитектуре агента от Tavily. Разница в сценариях с 5+ шагами — ощутимая.

А что если нет времени писать адаптер?

Мы выложили на Hugging Face готовые адаптеры для 10 популярных фреймворков. Просто запустите:

python run_benchmark.py --adapter-path adapters/ --auto-detect

Система сама определит, какие библиотеки установлены в окружении, и прогонит их. Результат появится на публичном дашборде.

Кстати, если вы пишете свой фреймворк с нуля — посмотрите на AgentCrawl: там показано, как строить тулы с graceful degradation.

Трещина в фундаменте: чего бенчмарк не меряет

Скажу честно: наш бенчмарк не идеален. Он не покрывает долгосрочную автономию (agent working 24/7), интеграцию с внешними системами (CRM, ERP) и безопасность (prompt injection). Это сознательное ограничение — мы хотели дать инструмент для быстрой оценки, а не «серебряную пулю».

Если вам нужно тестирование на реальных сайтах (например, заполнение форм) — я бы посоветовал ClawBench. Для длительных исследований с генерацией отчетов — 24hr-research-agent. А вот если вам нужно понять, вывезет ли библиотека типовой production-сценарий с 10 разными тулами — AgentEval вам в помощь.

Попробуйте сами. Ссылка на репозиторий: github.com/huggingface/agent-eval-benchmark. Fork, адаптируйте, дорабатывайте — и пусть ваши агенты больше не падают на ровном месте.

Подписаться на канал