ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Полный production агент

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

Создать production-ready AI-агента, способного самостоятельно выполнять задачи, делегировать подзадачи другим агентам и обеспечивать полную наблюдаемость (observability). Реализовать CI/CD пайплайн для автоматической сборки, тестирования и деплоя агента на staging-окружение. Основной фокус — на отказоустойчивости, мониторинге и повторяемости деплоя, чтобы агент был готов к реальному эксплуатационному окружению.

Ключевой результат Рабочий AI-агент, развёрнутый в Docker-контейнере, с автоматическим CI/CD, централизованными логами, метриками и трейсингом, который демонстрирует корректное делегирование задач и обработку ошибок.

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

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

1. Вместо коммерческого LLM API используем локальную модель (Ollama с llama3.2:1b) — настройте docker-compose.yaml с Ollama.
2. Для observability при отсутствии Grafana Cloud разверните локально docker-compose с Prometheus, Loki, Tempo и Grafana по шаблону из документации.
3. CI/CD — если нет доступа к GitHub Actions, используйте локальный GitLab CE в контейнере или просто bash-скрипты с act для эмуляции.
4. Для имитации внешних сервисов создайте dummy-сервер на FastAPI, возвращающий фиктивные данные.

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

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

Этап 1: Проектирование архитектуры агента (4 часа)

Действия

1. Определить сценарии использования — выбрать 2-3 типовых задачи (например, анализ новостей, бронирование встречи, ответ на email) и разбить их на подзадачи.
2. Спроектировать мультиагентную структуру — выделить роли: Coordinator (главный), Specialist (исполнители), Monitor (журналирование). Нарисовать диаграмму последовательности.
3. Описать интерфейсы делегирования — каждый специализированный агент должен принимать задачу через единый интерфейс и возвращать результат. Способ передачи: асинхронный (через redis pub/sub) или синхронный (вызов функции).
4. Определить наблюдаемость — решить, какие метрики собирать (latency, success rate, активные задачи), какие логи писать (старт/конец задачи, ошибки) и какой трейсинг (один трассировочный идентификатор на весь цикл).

Ожидаемый результат этапа Markdown-документ с архитектурой, диаграммой и контрактами взаимодействия агентов.

Этап 2: Реализация ядра агента с делегированием (12 часов)

Действия

1. Инициализировать проект — создать Python-проект с pyproject.toml, poetry, структурой папок src/, tests/, config/.
2. Подключить выбранный агентный фреймворк — например, CrewAI: определить Agent, Task, Crew.
3. Реализовать Coordinator-агента — он принимает пользовательский запрос, разбивает на шаги (с помощью LLM) и делегирует их Specialist-агентам.
4. Реализовать специализированные агенты — например, NewsAnalystAgent, CalendarAgent, EmailAgent. Каждый использует свои инструменты (API вызовы, чтение файлов).
5. Добавить механизм обработки ошибок делегирования — retry (до 3 раз с экспоненциальной задержкой), fallback (передать задачу другому агенту), логирование неудач.
6. Покрыть модульными тестами — не менее 10 тестов на ключевую логику (парсинг запросов, делегирование, обработка ошибок).

# Пример интерфейса делегирования
class DelegationInterface(ABC):
    @abstractmethod
    def delegate(self, task: str, context: dict) -> str: ...

Ожидаемый результат этапа Рабочее ядро агента с делегированием, протестированное на 3 сценариях.

Этап 3: Интеграция observability (8 часов)

Действия

1. Установить OpenTelemetry SDK в проект (opentelemetry-distro, opentelemetry-exporter-otlp). Инициализировать tracer и meter в __init__.py.
2. Добавить автоматическую инструментацию для HTTP-вызовов (если агент обращается к внешним API) и для внутренних вызовов агентов.
3. Создать кастомные метрики — agent.request.duration (гистограмма), agent.tasks.completed (счётчик), agent.delegation.errors (счётчик).
4. Настроить сбор логов через OpenTelemetry или напрямую в Loki — добавить библиотеку loguru, форматировать логи как JSON с trace_id и span_id.
5. Развернуть observability стек локально через docker-compose (docker-compose.observability.yaml), включая Prometheus, Loki, Tempo, Grafana.
6. Создать дашборд в Grafana — визуализировать latency (p50, p95), успешность, количество активных задач, логи ошибок.
7. Протестировать — запустить агента на 10 запросах, убедиться, что трейсы, метрики и логи попадают в систему.

Ожидаемый результат этапа Дашборд в Grafana (localhost:3000), отражающий состояние агента в реальном времени.

Этап 4: Настройка CI/CD (8 часов)

Действия

1. Создать Dockerfile — мультистадийная сборка: первый слой — зависимости, второй — копирование кода, установка agent framework, entrypoint.
2. Настроить docker-compose.yaml — сервис агента + сервисы observability + Ollama (если локальная модель).
3. Добавить GitHub Actions workflow (.github/workflows/deploy.yml):
   • Запуск линтеров (ruff, mypy), тестов (pytest) при push в main.
   • Сборка Docker-образа и пуш в GitHub Container Registry (или Docker Hub).
   • Деплой на staging-сервер через SSH или с помощью docker-compose up.
4. Настроить интеграционные тесты в CI — после деплоя запустить скрипт, проверяющий ответ агента на тестовый запрос с использованием requests к API агента.
5. Добавить секреты в GitHub Actions — API-ключи (LLM, внешние сервисы), доступ к реестру.

Ожидаемый результат этапа Работающий CI/CD pipeline, при мерже PR в main автоматически деплоится новая версия агента.

Этап 5: Интеграционное тестирование и деплой на staging (4 часа)

Действия

1. Развернуть staging окружение на VPS или локально через docker-compose с отдельным профилем (staging).
2. Провести нагрузочное тестирование — с помощью locust или vegeta отправить 50 запросов к Coordinator агенту, замерить p95 latency и процент ошибок.
3. Проверить наблюдаемость — после нагрузки проверить дашборд Grafana, убедиться, что все метрики отображаются, трейсы не теряются.
4. Выполнить smoke-тест — запустить один из сценариев полностью (делегирование 3 задач), проверить корректность итогового ответа.
5. Задокументировать инструкцию по запуску и администрированию — README.md с требованиями, шагами деплоя, ссылками на Grafana.

Ожидаемый результат этапа Полностью готовая к production эксплуатации версия агента на staging, прошедшая нагрузочное тестирование.

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

• Агент корректно принимает запрос, разбивает на подзадачи и делегирует их специализированным агентам.
• Механизм делегирования включает retry и fallback (при недоступности агента — передать другому).
• Все действия агента логируются в структурированные JSON-логи с trace_id, которые отправляются в Loki.
• В Grafana настроен дашборд с метриками latency, успешности, активных задач и логами ошибок.
• CI/CD pipeline проходит без ошибок: линтеры, тесты, сборка образов, пуш в registry.
• После CI/CD деплоя агент доступен на staging-урле (http://localhost:8080 или внешний IP) и отвечает на healthcheck.
• Нагрузочный тест (50 запросов) показывает p95 latency < 10 секунд и долю ошибок < 5%.
• Репозиторий содержит README с инструкцией по запуску (локально и через CI/CD), описание архитектуры и наблюдаемости.

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

Основной артефакт Git-репозиторий со следующей структурой:

• src/ — код агента и специализированных агентов.
• tests/ — модульные и интеграционные тесты.
• config/ — конфигурационные файлы (LLM, инструменты, observability).
• deploy/ — Dockerfile, docker-compose.yaml, файлы для observability.
• .github/workflows/deploy.yml — CI/CD пайплайн.
• docs/ — архитектурная диаграмма, postman-коллекция.
• README.md — описание, быстрый старт, настройка окружения.

Дополнительные результаты

• Дашборд Grafana (экспортированный JSON).
• Набор метрик и трейсов, подтверждающих работоспособность.
• CI/CD лог последнего успешного прогона.

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

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

Примечание Для первого раза рекомендуется заложить до 40 часов с учётом изучения инструментов.

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

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

• Я настроил локальное окружение (Docker, Python, ключи) и все зависимости установлены.
• Я реализовал делегирование с поддержкой retry и fallback, проверил на отрицательных сценариях.
• Я проверил, что метрики и логи отправляются в систему observability (написал маленький тестовый запрос и посмотрел в Grafana).
• Я запустил CI/CD workflow в своём репозитории, убедился что все этапы зелёные.
• Я задокументировал архитектуру, дашборд и инструкцию по деплою в README, чтобы любой другой разработчик мог повторить.