ТЕХНИЧЕСКОЕ ЗАДАНИЕ: РЕАЛИЗОВАТЬ HIERARCHICAL COORDINATION (SUPERVISOR → 3 WORKER)

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

Разработать прототип иерархической системы с одним Supervisor-агентом и тремя Worker-агентами, в которой Supervisor декомпозирует пользовательскую задачу на подзадачи и распределяет их между воркерами, а затем собирает и объединяет результаты. Основной фокус — на корректной логической декомпозиции задачи, эффективной коммуникации между агентами и робастной сборке финального ответа.

Ключевой результат Работающая система, способная принять сложное задание (например, «Проанализируйте трёх конкурентов компании X по заданным критериям»), разбить его на три независимых подзадачи, выполнить их параллельно и сформировать единый отчёт. Декомпозиция должна быть логичной, без избыточности или пропусков.

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

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

1. Используем локальную LLM через Ollama (например, ollama run llama3) и библиотеку langchain-ollama.
2. В качестве «воркеров» можно написать заглушки, которые просто возвращают фиксированный ответ для проверки логики декомпозиции.
3. Для имитации Supervisor-агента без LLM — написать простой парсер, который ищет ключевые слова и на их основе делит задачу (но это не рекомендуется, лучше минимальный LLM-агент).

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

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

Этап 1: Проектирование архитектуры и протокола (40 мин)

Действия

1. Определить роли агентов:
   • Supervisor: получает задачу пользователя, декомпозирует её на 3 подзадачи, назначает каждой Worker-агенту, собирает результаты, проверяет корректность, формирует итоговый ответ.
   • Worker 1/2/3: независимо выполняют свою подзадачу, возвращают результат в структурированном виде.
2. Спроектировать формат сообщений (Pydantic модели):
   • Task (описание, id, expected_output_schema).
   • Subtask (id, description, worker_id, parent_task_id).
   • WorkerResult (subtask_id, content, status).
   • FinalReport (summary, sections: list of WorkerResult, conclusion).
3. Продумать механизм повторных попыток при сбое воркера (retry + fallback).
4. Нарисовать диаграмму потоков (диаграмма последовательности, включить в README).

Ожидаемый результат этапа Документ (текстовый или PDF) с описанием архитектуры и протокола, а также Pydantic модели в файле agents/models.py.

Этап 2: Реализация Supervisor-агента (1 ч 30 мин)

Действия

1. Написать системный промпт для Supervisor, который явно предписывает:
   • Проанализировать задачу пользователя.
   • Разбить на ровно три логически независимые подзадачи (если задача не делится естественно — придумать три аспекта).
   • Для каждой подзадачи указать её описание, формат ожидаемого результата.
   • Вернуть результат в JSON-формате с ключами subtasks (список из 3 объектов).
2. Реализовать функцию supervisor_decompose(user_task: str) -> list[Вики/Subtask|Subtask, которая вызывает Вики/GPT-4o|LLM с этим промптом и парсит ответ через Вики/Pydantic|Pydantic.
3. Добавить валидацию: если подзадач не 3 — повторить запрос (до 2 попыток).
4. Реализовать метод collect_and_synthesize(results: list[WorkerResult]) -> FinalReport, который принимает результаты воркеров и формирует итоговый ответ — также через отдельный вызов LLM с инструкцией объединить.
5. Включить обработку ошибок: таймаут на LLM-вызов (10 секунд), логирование каждого шага.

Ожидаемый результат этапа Файл agents/supervisor.py с классами и функциями для декомпозиции и синтеза. Возможность вызвать Supervisor из отдельного скрипта и получить JSON с подзадачами.

Этап 3: Реализация Worker-агентов (1 ч)

Действия

1. Создать базовый класс BaseWorker с атрибутами name: str, llm_interface.
2. Реализовать метод execute(subtask: Subtask) -> WorkerResult:
   • Формирует промпт: «Ты эксперт в области {subtask.description}. Ответь максимально подробно и структурированно. Формат: JSON с ключами: answer, used_sources.»
   • Вызывает LLM.
   • Обрабатывает ошибки (если ответ невалидный — возвращает статус error с сообщением).
3. Создать три экземпляра с разными name (Worker-Alpha, Worker-Beta, Worker-Gamma) для имитации разных экспертиз. В промпте можно добавить различие, например, стиль ответа (аналитический, креативный, фактологический).
4. Написать тестовый вызов с фиктивной подзадачей.

Ожидаемый результат этапа Файл agents/worker.py с классом Worker, способным выполнять подзадачу и возвращать результат.

Этап 4: Интеграция и координация (1 ч 30 мин)

Действия

1. Создать главный класс HierarchicalSystem, который:
   • Инициализирует одного Supervisor и трёх Workers.
   • Имеет метод run(user_task: str) -> FinalReport.
2. В методе run:
   • Вызвать supervisor.decompose(user_task).
   • Создать асинхронные задачи (asyncio.create_task) для каждого Worker.
   • Дождаться их выполнения (asyncio.gather).
   • Передать результаты в supervisor.collect_and_synthesize.
3. Реализовать обработку случая, если какой-то Worker не ответил (таймаут 15 секунд) — заполнить результат заглушкой.
4. Добавить логирование хода работы (уровень INFO): декомпозиция, старт воркеров, получение результатов, финальный ответ.
5. Написать скрипт main.py, который принимает задачу из аргументов командной строки или из стандартного ввода, запускает систему и выводит итоговый отчёт.

Ожидаемый результат этапа Рабочая программа, которая может быть запущена командой python main.py "Моя сложная задача" и выводит финальный отчёт.

Этап 5: Тестирование и оценка декомпозиции (1 ч)

Действия

1. Подготовить 3 тестовые задачи разной сложности (см. п.2 «Исходные данные»).
2. Запустить систему на каждой задаче, записать:
   • Исходная задача.
   • Сгенерированные подзадачи (декомпозиция).
   • Ответы воркеров (сырые).
   • Финальный отчёт.
3. Оценить качество декомпозиции по критериям:
   • Подзадачи не пересекаются по смыслу.
   • Покрывают все аспекты исходной задачи.
   • Каждая подзадача выполнима одним агентом (без дополнительной координации).
4. Если декомпозиция неудовлетворительна — скорректировать промпт Supervisor (итеративно).
5. Создать папку tests/ с тремя JSON-файлами, содержащими входные задачи и ожидаемый паттерн декомпозиции.
6. Написать unit-тесты на валидацию моделей и обработку ошибок (pytest).

Ожидаемый результат этапа Оценка качества декомпозиции в виде краткого отчёта (можно включить в README). Папка tests/ с unit-тестами и примерами.

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

• Supervisor на основе LLM корректно декомпозирует задачу ровно на 3 подзадачи, логически связанные с исходной.
• Worker-агенты выполняют свои подзадачи параллельно (общее время выполнения системы не превышает max(worker_time) + overhead).
• Финальный отчёт (FinalReport) содержит введение от Supervisor, по одному разделу от каждого Worker и заключение.
• Код системы модульный: классы Supervisor, Worker и HierarchicalSystem находятся в отдельных файлах в пакете agents.
• Реализована обработка ошибок: таймауты, повторные попытки декомпозиции (до 2 раз), fallback-ответы при сбое воркера.
• В репозитории присутствует README с описанием архитектуры, инструкцией по запуску и примерами.
• Unit-тесты (pytest) проходят минимум на 80% покрытия ключевой логики (декомпозиция, валидация, сборка).

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

• Файл с кодом: main.py (точка входа), agents/__init__.py, agents/models.py, agents/supervisor.py, agents/worker.py, agents/system.py.
• Файл с тестами: tests/test_models.py, tests/test_system.py, tests/fixtures/.
• Файл README.md с описанием, диаграммой последовательности (ASCII или ссылка на файл), инструкцией по запуску, примерами задач и ожидаемыми результатами.
• Опционально Видеодемонстрация (1-2 минуты) работы системы.

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

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

Примечание Для первого выполнения задачи (без опыта работы с hierarchical multi-agent) рекомендуется заложить дополнительно 2 часа на отладку и коррекцию промптов.

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

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

• Я проверил, что YAML frontmatter корректен (теги, задача).
• В ТЗ описана конкретная, измеримая цель (Ключевой результат).
• Каждый этап содержит точные действия и ожидаемые результаты.
• Технологический стек указан реально (можно выполнить без коммерческих лицензий).
• Критерии приемки можно проверить автоматизированно или вручную за 5 минут.
• Чек-лист самопроверки заполняется в конце выполнения.