ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Создать benchmark для агентов

1. Цель задачи

Разработать эталонный набор тестов (benchmark) из 200 запросов для оценки качества AI-агентов, выполняющих многошаговые действия. Каждый запрос сопровождается эталонной траекторией — последовательностью действий, которые агент должен совершить для успешного завершения задачи. Ключевой результат готовый датасет в формате JSON, метрики и скрипт оценки, позволяющие измерить успешность агента на golden set из 20 запросов с порогом >0.9.

2. Исходные данные

Если нет реального инструмента — симулируем:

1. Генерация запросов — использовать openai.ChatCompletion с промптом, запрашивающим реалистичные задачи для агента (например, "Спланируй поездку в Берлин: найди билеты, отель, составь список достопримечательностей").
2. Генерация эталонных траекторий — после ручного написания 5 примеров, дообучить LLM на этих примерах (few-shot) и автоматически сгенерировать траектории для остальных, затем проверить и откорректировать.
3. Среда выполнения — вместо реального веб-браузера или API использовать мок-объекты с возможностью возврата предопределённых ответов (mock servers на flask).

3. Технологический стек

4. Этапы выполнения

Этап 1: Определение домена и структуры benchmark (2 часа)

Действия

1. Выбрать 3–4 домена, где агенты проявляют полезность: онлайн-бронирование, работа с документами, поиск информации, планирование.
2. Определить типы траекторий: последовательные (линейные), ветвящиеся (условные), циклические (повторяющиеся попытки).
3. Разработать единый формат записи запроса и траектории. Пример структуры JSON:

   {
     "id": "task_001",
     "domain": "travel",
     "prompt": "Забронируй билет на поезд из Москвы в Санкт-Петербург на 15 мая...",
     "golden_trajectory": [
       {"action": "search_flights", "parameters": {"from": "Москва", "to": "СПб", "date": "2025-05-15"}},
       {"action": "select_option", "parameters": {"index": 2}},
       {"action": "confirm_booking", "parameters": {"email": "user@example.com"}}
     ],
     "expected_outcome": "Билет куплен, письмо отправлено",
     "allowed_actions": ["search_flights", "select_option", "confirm_booking"],
     "hard_constraints": ["Обязательно email"]
   }
   

4. Зафиксировать 5 правил валидации траекторий (например, каждый шаг должен быть атомарным, не должно быть лишних действий).

Ожидаемый результат этапа Документ-спецификация benchmark с примерами формата и правилами.

Этап 2: Генерация 200 запросов с ожидаемыми траекториями (8 часов)

Действия

1. Написать скрипт generate_benchmark.py, который:
   • Получает домен, количество запросов.
   • Использует few-shot промпт с 3 примерами из этапа 1.
   • Запрашивает GPT-4o mini сгенерировать n пар (prompt, golden_trajectory).
   • Сохраняет результат в JSON-массив.
2. Запустить генерацию: 50 запросов на домен (4 домена = 200). Пример промпта:

   Сгенерируй задачу для AI-агента в домене "travel". Задача должна включать 3-5 шагов.
   Верни JSON с полями: id (task_001), prompt, golden_trajectory (массив объектов с action и parameters).
   Используй список разрешённых действий: search_flights, search_hotels, book_ticket, confirm_payment.
   Пример вывода:
   {"id": "task_001", "prompt": "Забронируй перелёт Москва-Париж...", "golden_trajectory": [{"action": "search_flights", ...}]}
   

3. Вручную проверить и отредактировать первые 20 запросов (golden set). Для этого:
   • Запустить каждого из 20 промптов на эталонном агенте (из этапа 3).
   • Сравнить траекторию агента с предложенной LLM; при расхождении скорректировать golden_trajectory.
4. Оставшиеся 180 запросов пропустить через автоматическую валидацию:
   • Проверить, что все шаги используют только разрешённые действия.
   • Проверить, что траектория не пуста и не содержит дублирующихся шагов.
   • Отбраковать невалидные (ожидать не более 5% брака); при большем проценте — улучшить промпт.

Ожидаемый результат этапа Файл benchmark_v1.json с 200 запросами, из которых 20 помечены как "golden": true.

Этап 3: Разработка метрик и скрипта оценки (3 часа)

Действия

1. Определить метрики:
   • success_rate — доля задач, где агент в точности повторил golden_trajectory (порядок и действия совпадают).
   • partial_accuracy — доля шагов, совпадающих с golden (без учёта порядка).
   • coverage — доля запросов, где агент выполнил хотя бы один шаг.
   • exact_match (только для golden set) — 1 если все шаги совпали, иначе 0.
   • success_rate_golden — success_rate на golden set.
2. Написать скрипт evaluate.py, который:
   • Загружает benchmark JSON и лог агента (JSON-файл с траекторией, которую выполнил агент).
   • Сравнивает поэлементно списки действий (игнорируя незначительные различия в параметрах, если они не влияют на результат).
   • Вычисляет метрики и выводит таблицу.
3. Реализовать функцию fuzzy_compare для случая, когда agent_trajectory содержит дополнительные шаги:

   def trajectory_match(golden, actual):
       # greedy matching: для каждого шага golden ищем совпадение в actual
       used = set()
       matches = 0
       for step in golden:
           for i, a_step in enumerate(actual):
               if i in used: continue
               if actions_match(step, a_step):
                   matches += 1
                   used.add(i)
                   break
       return matches / len(golden) if golden else 0
   

4. Создать dummy-лог агента для проверки скрипта.

Ожидаемый результат этапа Рабочий скрипт evaluate.py, который выводит метрики в консоль и сохраняет результаты в eval_results.json.

Этап 4: Пилотирование на эталонном агенте (4 часа)

Действия

1. Собрать простого ReAct-агента на LangChain:
   • Использовать ChatOpenAI (GPT-4o-mini) как "мозг".
   • Подключить инструменты: Wikipedia, Calculator, FileSystem (только чтение), SimpleWebSearch (mock, возвращает заранее заданные страницы).
   • Код агента в agent.py.
2. Ограничить max_iterations до 10 шагов.
3. Запустить агента на всех 200 запросах (можно с использованием asyncio для ускорения) и сохранить логи в agent_logs/.
4. Прогнать evaluate.py на полученных логах.
5. Проанализировать слабые места: на каких запросах success_rate низкий? Если на golden set success_rate < 0.9:
   • Исправить ошибки в golden_trajectory (возможно, они неоптимальны).
   • Улучшить инструкции для агента (system prompt).
   • Повторить замер до достижения порога >0.9.
6. Зафиксировать финальные версии benchmark и логов.

Ожидаемый результат этапа Подтверждение, что эталонный агент проходит golden set с success_rate >0.9; таблица метрик по всем 200 задачам.

Этап 5: Документация и упаковка (2 часа)

Действия

1. Оформить репозиторий со структурой:

   benchmark_agent/
   ├── data/
   │   ├── benchmark.json
   │   └── golden_indices.txt (список id golden-задач)
   ├── agent/
   │   ├── agent.py
   │   └── tools.py
   ├── evaluate/
   │   ├── metrics.py
   │   └── evaluate.py
   ├── generate/
   │   └── generate_benchmark.py
   └── README.md
   

2. Написать README с описанием:
   • Формат benchmark.
   • Инструкция по запуску оценки.
   • Пример использования.
3. Запустить линтеры (ruff, black) и убедиться в чистоте кода.
4. Сделать commit и push в ветку main.

Ожидаемый результат этапа Публичный репозиторий с полностью документированным benchmark.

5. Критерии приемки (Definition of Done)

• Файл benchmark.json содержит ровно 200 записей с корректной структурой (id, prompt, golden_trajectory, allowed_actions).
• 20 записей помечены флагом "golden": true.
• Все шаги траекторий используют только разрешённые действия из соответствующего списка.
• Скрипт evaluate.py запускается без ошибок и выводит success_rate, partial_accuracy, coverage.
• При прогоне на golden set через эталонного агента (ReAct) success_rate_golden >= 0.9.
• В репозитории есть документация (README), описывающая формат и использование.
• Код отформатирован согласно PEP8 (ruff score A).
• Генерация benchmark воспроизводима: при повторном запуске generate_benchmark.py с тем же seed получается идентичный результат.

6. Ожидаемый результат

Основной артефакт — папка benchmark_agent/, содержащая:

• data/benchmark.json — эталонный датасет из 200 запросов и траекторий.
• evaluate/evaluate.py — скрипт для автоматической оценки агента.
• agent/agent.py — пример эталонного агента для пилотирования.
• README.md — документация.

Дополнительные результаты: eval_results.json с метриками для эталонного агента, лог выполнения agent_logs/.

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание Для первого выполнения задачи рекомендуется увеличить бюджет до 24 часов, заложив 5 часов на отладку и доработку golden set.

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я убедился, что все 200 запросов имеют корректный JSON без синтаксических ошибок.
• Я прогнал evaluate.py на двух случайных golden-задачах и получил ожидаемые метрики.
• Я сравнил три сгенерированные траектории с ручными и убедился в их разумности.
• Я проверил, что скрипт generate_benchmark.py воспроизводим (одинаковый seed → одинаковый вывод).
• Я прочитал README так, как если бы я был новым пользователем, и выполнил шаги "install → evaluate" без ошибок.