google-agents-cli-eval

Google Agents CLI Eval — навык для оценки ADK-агентов: подготовки eval-наборов, запуска инференса, выставления метрик, анализа неудач, сравнения результатов и итерационного улучшения агента. Официальный SKILL.md связывает эти операции с методологией Quality Flywheel. Он не предназначен для API-кода, развёртывания или начального scaffolding проекта: для этих задач в репозитории указаны отдельные навыки. Основной результат здесь — воспроизводимая оценка поведения агента по данным и трассам. Для работы нужен agents-cli; исходник указывает установку через uv tool install google-agents-cli. Quality Flywheel состоит из пяти стадий. Сначала подготавливаются данные: можно начать с одного-двух случаев в базовом JSON-наборе. Затем agents-cli eval generate запускает агента на наборе и сохраняет трассы в artifacts/traces/. После этого agents-cli eval grade оценивает трассы и пишет JSON/HTML-результаты в artifacts/grade_results/; выставление оценок является обязательной стадией независимо от того, как появились трассы. Далее изучаются проваленные метрики и причины по последнему JSON или HTML. Наконец, инструкции агента, описания инструментов или набор данных корректируются по найденной причине. Для обычного пути команда agents-cli eval run объединяет generate и grade. Если исходных примеров недостаточно, в навыке есть opt-in-команда agents-cli eval dataset synthesize: она моделирует пользовательские сценарии и сразу создаёт трассы, поэтому отдельный этап generate после неё пропускается. Для анализа десяти и более проваленных случаев можно применить agents-cli eval analyze, но это LLM-ориентированная кластеризация, а не обязательная замена ручной проверки. После каждого исправления исходник рекомендует agents-cli eval compare между предыдущим и новым JSON, чтобы проверить улучшение целевой метрики без регрессий в остальных. Выбор метрики зависит от того, что именно нужно проверить. multi_turn_task_success показывает достижение цели пользователя; multi_turn_trajectory_quality — логичность и эффективность траектории; multi_turn_tool_use_quality — качество вызовов инструментов; final_response_quality — качество финального ответа без обязательного эталона; hallucination — фактическую обоснованность; safety — соблюдение политики безопасности. Для узкой предметной проверки можно написать собственную LLMMetric или CodeExecutionMetric. Низкий результат не следует исправлять снижением порога или удалением нестабильного кейса: в руководстве это названо сокрытием сигнала, а не решением проблемы. Навык задаёт полезные границы стоимости и интерпретации. GEPA-оптимизация prompts описана как дорогая и длительная: её не следует запускать без явного запроса, а перед ней нужно сначала сделать ручные исправления. Локальный generate по умолчанию поднимает локальный HTTP-сервер, если в проекте есть fast_api_app.py, либо использует adk api_server; при необходимости можно указать уже запущенный endpoint и имя приложения. Синтезированные или ручные наборы, трассы и grade-результаты нужно хранить раздельно, чтобы сравнение ссылалось на реальные артефакты. Eval подтверждает изменение поведения на выбранных случаях, но не является доказательством качества на всех возможных запросах: покрытие набора, выбранные метрики, конфигурация judge и интерпретация провалов остаются ответственностью команды.