Agent‑EvalKit: как системно тестировать AI‑агентов прямо в IDE

Что нового

AWS выложила в open source (Apache 2.0) Agent‑EvalKit — тулкит для системной оценки AI‑агентов. Главная идея: вы не уходите в отдельную платформу, а запускаете весь цикл оценки через уже установленного AI‑ассистента для кода:

• Поддерживаются AI‑ассистенты: Claude Code, Kiro CLI, Kilo Code.
• Интеграция с агентными фреймворками: Strands Agents SDK, LangGraph, CrewAI (через OpenTelemetry‑трейсинг).
• Шесть фаз оценки, каждая — отдельная slash‑команда в ассистенте:
  • /evalkit.plan — план оценки.
  • /evalkit.data — генерация тест‑кейсов.
  • /evalkit.trace — автоматическая инструментализация трейсинга.
  • /evalkit.run_agent — прогоны агента по тестам с записью трейсинга.
  • /evalkit.eval — запуск метрик и вычисление оценок.
  • /evalkit.report — отчёт с рекомендациями по конкретным строкам кода.
• Есть «мастер» для первого запуска: /evalkit.quick — проводит через все шесть фаз по шагам.
• Из коробки поддерживаются библиотеки для метрик: DeepEval и Strands Evals SDK.
• Все артефакты сохраняются в локальную папку eval/ (план, тест‑кейсы, трейсинги, результаты метрик, отчёт).

Из показательного кейса в блоге:

• Исследовательский travel‑агент на Strands Agents SDK и Amazon Bedrock.
• Agent‑EvalKit сгенерировал 100 многотуровых сессий (диалоги) по сценариям: выбор направления, сезонность, маршрут, сравнение вариантов, бюджет.
• По итогам оценки:
  • Response Quality (качество ответа) — 83,9%.
  • Tool Parameter Accuracy (точность параметров инструментов) — 64,5%.
  • Faithfulness (опора на реальные данные) — всего 32,3%.
• Выявленный паттерн: агент придумывал курсы валют, температуру и детали достопримечательностей, когда web‑поиск возвращал пустой или неполный ответ.

Как это работает

Agent‑EvalKit не запускает отдельный SaaS‑интерфейс. Вместо этого AWS использует ваш AI‑ассистент как «двигатель» всей оценки: ассистент читает код, пишет вспомогательные скрипты и анализирует результаты. Вся логика завязана на slash‑команды и обычный текстовый промпт.

Архитектура по шагам:

1. Чтение кода агента

   • Ассистент через /evalkit.plan просматривает исходники вашего агента: системный промпт, описания инструментов, конфигурацию фреймворка.
   • На основе этого строит «ментальную модель»: какие инструменты доступны, какие шаги пайплайна, где потенциальные точки отказа.

2. План оценки (Plan)

   • Команда: /evalkit.plan <ваш запрос>.
   • На вход вы даёте приоритеты: например, «проверь галлюцинации на пустых ответах инструментов», «сфокусируйся на точности параметров API».
   • На выходе — формальный план: список метрик и конкретные методы их расчёта (какая библиотека, какие поля трейсинга использовать).

3. Генерация тест‑данных (Data)

   • Команда: /evalkit.data.
   • EvalKit синтезирует тест‑кейсы, строго опираясь на план: входные запросы, ожидаемые результаты, сценарии отказа.
   • Можно подставить свои данные: логи продакшена, ручные тесты. В этом случае toolkit не генерирует, а адаптирует существующий датасет.

4. Инструментализация трейсинга (Trace)

   • Команда: /evalkit.trace.
   • В код агента добавляются вызовы OpenTelemetry‑совместимого трейсинга.
   • Для поддерживаемых фреймворков (Strands, LangGraph, CrewAI) ассистент определяет стек и встраивает нужный код автоматически.
   • В трейс попадает полный путь выполнения: какие инструменты вызваны, с какими параметрами, что они вернули, какие промежуточные ответы сгенерировала модель.

5. Прогон агента (Run agent)

   • Команда: /evalkit.run_agent.
   • Агент последовательно обрабатывает каждый тест‑кейс.
   • Для каждого прогона создаётся структурированный trace‑файл с историей всех шагов.

6. Вычисление метрик (Eval)

   • Команда: /evalkit.eval.
   • Toolkit превращает план метрик в исполняемый код: конфигурирует DeepEval или Strands Evals SDK.
   • Метрики работают не только по финальному ответу, но и по трейсингу: можно оценить, насколько ответ опирается на реальные данные инструментов, где агент пропустил валидацию и т.п.

7. Отчёт и рекомендации (Report)

   • Команда: /evalkit.report.
   • Ассистент анализирует все тест‑кейсы, трейсинги и метрики.
   • Результат — приоритезированный список рекомендаций с привязкой к конкретным файлам и строкам кода.
   • Каждая рекомендация содержит предполагаемый эффект: что именно улучшится (например, уменьшение галлюцинаций при пустых ответах инструментов).

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

Почему одного «совпадения ответа» мало

Обычные тесты для бэкенда проверяют: «ответ совпал с эталоном — тест прошёл». Для агентов этого недостаточно:

• Агент может выдать красивый, логичный ответ и при этом полностью выдумать факты, потому что инструмент вернул пустой результат.
• Или агент может угадать правильный ответ, но нарушить внутренний протокол: не вызвать нужный инструмент, пропустить проверку, не обработать ошибку.

Agent‑EvalKit решает это за счёт трёх классов метрик:

• Faithfulness — насколько ответ опирается на данные, которые реально вернули инструменты.
• Tool Parameter Accuracy — насколько корректно агент вызывает инструменты: правильные параметры, типы, диапазоны.
• Response Quality — удобство и ясность ответа для человека.

При этом toolkit комбинирует два подхода:

• Кодовые метрики — быстрые и воспроизводимые, но плохо переносят допустимые вариации ответа.
• LLM‑as‑judge — более тонкая оценка качества и связности, но требует вызова базовой модели через Amazon Bedrock и аккуратного промпта.

Финальная цель — не просто выдать числа, а привести к конкретным изменениям в коде. Поэтому отчёт всегда заканчивается actionable‑рекомендациями, а не только графиками.

Что это значит для вас

Для кого это полезно

Agent‑EvalKit имеет смысл ставить, если вы:

• Пишете агентов, а не просто чат‑ботов: есть несколько инструментов, сложный пайплайн, внешний API.
• Используете Strands Agents SDK, LangGraph, CrewAI или похожие фреймворки.
• Разрабатываете продукт, где важно не только «красиво ответить», но и правильно работать с инструментами: финтех, тревел, аналитика, внутренние корпоративные ассистенты.
• Хотите прогонять регрессионные тесты при каждом релизе, а не разово «перед запуском».

Где Agent‑EvalKit помогает

1. Поиск скрытых галлюцинаций

Кейс из блога AWS — хороший ориентир. Команда видела, что travel‑агент иногда выдаёт «слишком точные» числа, но не понимала масштаб проблемы.

Agent‑EvalKit:

• Сгенерировал 100 диалогов по разным сценариям.
• Прогнал агента и записал трейсинги.
• Посчитал:
  • Response Quality — 83,9% (ответы понятные и полезные).
  • Tool Parameter Accuracy — 64,5% (обычно выбирает правильные инструменты, но иногда передаёт неточные параметры).
  • Faithfulness — 32,3% (массовые галлюцинации при пустых ответах web‑поиска).

Результат для команды: не абстрактное «агент иногда врет», а чёткий паттерн — пустые ответы инструментов → выдуманные данные → поданы как реальные. И рекомендации: добавить инструкции в системный промпт и улучшить обработку ошибок инструментов.

2. Отладка сложных цепочек инструментов

Если агент вызывает несколько внешних сервисов, Agent‑EvalKit помогает понять:

• Где он выбирает не тот инструмент.
• Где передаёт неправильные параметры (например, странные даты или валюты).
• Где игнорирует ошибки и продолжает работу с «мусорными» данными.

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

3. Встраивание оценки в цикл разработки

AWS предлагает использовать Agent‑EvalKit не как «один раз проверили и забыли», а как часть постоянного цикла:

• Запускайте оценку после каждого значимого изменения агента.
• Сравнивайте отчёты между версиями, чтобы видеть прогресс и ловить регрессии.
• Начинайте с 2–3 ключевых метрик (например, faithfulness + tool accuracy), потом расширяйте.
• Стройте CI/CD‑пайплайн, где каждый PR триггерит прогон Agent‑EvalKit, а проваленные метрики блокируют релиз.

4. Связка с продакшен‑мониторингом

AWS предлагает использовать:

• Amazon Bedrock AgentCore Observability — для сбора трейсингов с реального трафика.
• AgentCore Evaluation — для запуска метрик на этих трейсингах.

Agent‑EvalKit в этой картине работает как «лаборатория» в девелопменте, а AgentCore — как мониторинг в продакшене. Вместе они помогают увидеть новые типы ошибок, которые не попали в синтетические тесты.

Где не стоит переоценивать

• Agent‑EvalKit не заменяет ручную экспертизу доменных специалистов. AWS прямо советует периодически сравнивать оценки LLM‑как‑судьи с решениями людей и обновлять промпты, если оценки расходятся.
• Инструмент не бесплатен по вычислениям: для LLM‑метрик вам нужен доступ к базовым моделям через Amazon Bedrock. Чем больше тест‑кейсов и сложнее метрики, тем выше счёт.
• Если у вас простой чат‑бот без инструментов, выгода от трейсингов и сложных метрик будет минимальной.

Доступность из России

Agent‑EvalKit — это open source‑проект на GitHub, его можно установить из любого места, где доступен GitHub.

Но для полноценной работы вам понадобится:

• Активный аккаунт AWS.
• Включённый доступ к foundation‑моделям в Amazon Bedrock.

Если доступ к AWS и Bedrock в вашей сети ограничен, скорее всего потребуется VPN и аккаунт, который AWS не блокирует по региону. Без этого вы сможете поставить тулкит и локальные зависимости, но не запустите LLM‑метрики и часть сценариев.

Место на рынке

Agent‑EvalKit закрывает нишу оценки именно агентов, а не просто LLM‑ответов. В экосистеме уже есть несколько направлений:

• Классические фреймворки для тестирования LLM (DeepEval и др.) — дают метрики, но не строят end‑to‑end процесс от кода до отчёта.
• Облачные платформы для наблюдаемости и оценки (включая решения от других вендоров) — обычно работают как отдельные веб‑сервисы, с которыми надо интегрироваться.

Agent‑EvalKit делает упор на две вещи:

• Интеграция в IDE / терминал через существующих ассистентов (Claude Code, Kiro CLI, Kilo Code).
• Глубокая привязка к коду: план, тест‑кейсы, трейсинг, отчёт — всё строится на анализе исходников агента.

Прямых числовых сравнений с другими инструментами AWS не приводит. Из фактов можно зафиксировать:

• Toolkit использует уже существующие библиотеки метрик (DeepEval, Strands Evals SDK), а не изобретает свои формулы.
• В отличие от чисто облачных решений, основная работа идёт локально, а в облако уходит только inference для LLM‑метрик через Amazon Bedrock.

Если вы уже используете DeepEval или похожие библиотеки, Agent‑EvalKit выступает как «оркестратор» вокруг них: план, генерация данных, трейсинг, отчёт.

Установка

Для запуска Agent‑EvalKit вам нужны:

• Активный аккаунт AWS.
• Включённый доступ к foundation‑моделям в Amazon Bedrock (проверьте раздел Model access в консоли).
• Python 3.11 или новее.
• Git.
• Пакетный менеджер uv.
• Установленный и настроенный AI‑ассистент: Claude Code, Kiro CLI или Kilo Code.

Установка uv

На macOS и Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Установка Agent‑EvalKit

Устанавливаем тулкит напрямую из GitHub‑репозитория awslabs:

uv tool install evalkit --from git+https://github.com/awslabs/Agent-EvalKit.git

Создаём проект оценки и копируем туда код вашего агента:

evalkit init my-agent-evaluation
cd my-agent-evaluation
cp -r /path/to/your/agent .

В каталоге агента должны лежать:

• исходный код агента;
• описания инструментов;
• конфигурация запуска (настройки фреймворка, ключи окружения и т.п.).

Подробности по поддерживаемым фреймворкам и структуре проекта — в репозитории Agent‑EvalKit.

Как запустить

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

Стартуем AI‑ассистента внутри каталога проекта. Для Claude Code:

claude

Быстрый первый прогон

Для guided‑режима, который проведёт вас по всем шести фазам, используйте:

/evalkit.quick <your natural language guidance>

/evalkit.quick Evaluate my agent at ./my_agent for response quality and tool accuracy

Ассистент объяснит, что делает каждый шаг, и подскажет следующую команду.

Полный ручной контроль

Если хотите больше контроля, запускайте фазы по отдельности.

План оценки:

/evalkit.plan <your natural language guidance>

/evalkit.plan Evaluate my agent at ./my_agent for response quality and tool accuracy

Генерация тест‑данных:

/evalkit.data

Инструментализация трейсинга:

/evalkit.trace

Прогон агента по тест‑кейсам:

/evalkit.run_agent

Запуск метрик:

/evalkit.eval

Формирование отчёта:

/evalkit.report

AWS также показывает видео‑демо, где Agent‑EvalKit оценивает travel‑агента с web‑поиском и планированием по всем шести фазам — от анализа кода до финального отчёта.

Практические советы по использованию

AWS делится набором приёмов, которые помогают встроить Agent‑EvalKit в рабочий цикл.

1. Начните с узкого фокуса

• Не пытайтесь охватить всё сразу.
• Выберите 2–3 метрики, которые критичны для вашего кейса (например, faithfulness и точность инструментов).
• Расширяйте план, когда устраните первые проблемы и зафиксируете базовый уровень качества.

2. Используйте доменную экспертизу в промптах

• В каждой фазе давайте ассистенту конкретные указания: какие входы, крайние случаи и типичные сбои вы видели.
• Чем точнее инструкция, тем полезнее получатся тест‑кейсы, метрики и рекомендации.

3. Проверяйте тест‑кейсы руками

• Data‑фаза генерирует сценарии автоматически, но она не знает ваши реальные паттерны пользователей.
• Пройдитесь по сгенерированным кейсам, добавьте ситуации из продакшена.

4. Оценивайте после каждого значимого изменения

• Запускайте Agent‑EvalKit при крупных изменениях логики агента или инструментов.
• Сравнивайте отчёты между версиями, чтобы видеть, что действительно улучшилось, а что сломалось.

5. Исправляйте по одному пункту

• Начинайте с самой «дорогой» рекомендации из отчёта.
• Внесите правку, перезапустите оценку, убедитесь в улучшении.
• Переходите к следующему пункту.

6. Переиспользуйте артефакты

• Не регенерируйте всё при каждом запуске.
• Переиспользуйте существующие тест‑кейсы и трейсинг, а в отдельных фазах меняйте только фокус (например, добавить новую метрику).

7. Синхронизируйте автоматические оценки с людьми

• Периодически сравнивайте оценки LLM‑as‑judge с решениями ваших экспертов или аннотаторов.
• Обновляйте промпты оценщика, если видите расхождения.

8. Подключайте продакшен‑мониторинг

• Собирайте трейсинги с реального трафика через Amazon Bedrock AgentCore Observability.
• Прогоняйте по ним метрики через AgentCore Evaluation.
• Это помогает ловить новые типы ошибок, которые не попали в тестовый датасет.

Как встроить в CI/CD

AWS предлагает типовой сценарий интеграции Agent‑EvalKit в pipeline:

1. Разработчик пушит изменения в код агента.
2. CI запускает Agent‑EvalKit:
   • использует уже существующие тест‑кейсы и трейсинг;
   • прогоняет /evalkit.run_agent и /evalkit.eval.
3. Качество проверяется по порогам метрик и регрессиям относительно предыдущей версии.
4. Если пороги не соблюдены, пайплайн помечает изменения как не прошедшие проверку, а в отчёте появляются флаги по проблемным местам.

С течением времени стоимость одного прогона снижается, потому что вы переиспользуете большую часть артефактов (план, тест‑кейсы, трейсинг), а не создаёте всё заново.

Что делать после эксперимента

Если вы создали тестовый проект для знакомства с Agent‑EvalKit:

• Удалите директорию проекта, когда закончите.
• Если использовали foundation‑модели через Amazon Bedrock, загляните в раздел цен в консоли AWS, чтобы понять, сколько стоили прогонки.

Что дальше

Agent‑EvalKit даёт разработчикам способ превратить размытое «агент иногда ведёт себя странно» в конкретный список проблем, привязанных к строкам кода и подкреплённых метриками.

Если вы строите агентов, которые сами выбирают инструменты и принимают решения, простой чек «ответ похож на правду» уже не спасает. Нужен доступ к полному пути выполнения, систематические тест‑кейсы и понятные метрики — именно это закрывает Agent‑EvalKit.

Подробности, примеры и документацию ищите в репозитории Agent‑EvalKit на GitHub. Для обсуждений и вопросов AWS использует GitHub Discussions. Дополнительный контекст по подходу к автоматизации оценки агентов — в статье An Empirical Study of Automating Agent Evaluation.

---

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

• Veai 5.12: General‑агент, который сам решает — писать код, тестировать или дебажить
• Как LLMStart построила свой биллинг для ИИ-агента: микрокредиты, ОГРН и пять LLM за один запрос
• Как Microsoft Sentinel ловит «классические» AI‑агенты, которых не видит Entra Agent ID