core/engine/src/agents/planner.py - main - alexefan136/flowstack

core/engine/src/agents/planner.py
167 строк8 KB
Alexander Efanov
Обновление репозитория
15 июл 2026, 12:19
15 июл 2026, 12:1976704c6
# src/agents/planner.py
"""Агент-планировщик для декомпозиции сложных задач и создания планов выполнения.

Этот модуль предоставляет PlannerAgent — специализированного агента
для анализа сложных задач, их разбивки на подзадачи, определения
последовательности выполнения и оценки необходимых ресурсов.

Примеры использования:

    # Планировщик с дефолтными параметрами
    agent = PlannerAgent()
    result = await agent.run({
        "topic": "Разработать REST API для e-commerce платформы"
    })

    # Планировщик с кастомным именем
    agent = PlannerAgent(name="Technical Planner")

    # Планировщик с кастомным system prompt
    agent = PlannerAgent(
        name="Project Manager",
        system_prompt="Ты — опытный project manager..."
    )

    # Использование в мультиагентной системе
    plan = await planner.run({"topic": task})
    for subtask in plan["subtasks"]:
        result = await researcher.run({"topic": subtask})
"""
from __future__ import annotations

from .base import LLMAgent


class PlannerAgent(LLMAgent):
    """Агент для планирования и декомпозиции сложных задач.
    
    Специализируется на:
    - Анализе сложных задач и требований
    - Декомпозиции на атомарные подзадачи
    - Определении зависимостей между задачами
    - Приоритизации и оценке сложности
    - Создании пошаговых планов выполнения
    - Делегировании задач подходящим агентам
    
    Отличается от других агентов стратегическим мышлением:
    PlannerAgent не выполняет задачи сам, а создаёт детальный план
    их выполнения, который может быть использован оркестратором
    или другими агентами для пошаговой реализации.
    
    Идеально подходит для:
    - Планирования мультиагентных workflow
    - Декомпозиции сложных проектов
    - Создания roadmap для разработки
    - Оценки объёма работ и сроков
    """

    DEFAULT_SYSTEM_PROMPT = """Ты — опытный планировщик и архитектор решений с глубоким пониманием
процессов разработки, анализа и управления проектами. Твоя задача — 
превращать сложные, абстрактные задачи в конкретные, выполнимые планы.

## Твой процесс работы:

1. **Анализ задачи** — тщательно изучи исходную задачу:
   - Определи цель и ожидаемый результат
   - Выяви неявные требования и ограничения
   - Определи контекст и stakeholders

2. **Декомпозиция** — разбей задачу на атомарные подзадачи:
   - Каждая подзадача должна быть独立完成мой
   - Размер: от 15 минут до 2 часов работы
   - Чёткие критерии завершения (Definition of Done)

3. **Определение зависимостей** — выяви связи между подзадачами:
   - Какие задачи блокируют другие
   - Какие можно выполнять параллельно
   - Критический путь выполнения

4. **Приоритизация** — расставь задачи по важности и срочности:
   - P0 (критические) — без них проект невозможен
   - P1 (важные) — существенно влияют на результат
   - P2 (желательные) — улучшают качество
   - P3 (опциональные) — nice-to-have

5. **Делегирование** — определи подходящего агента для каждой задачи:
   - researcher — сбор информации и анализ
   - writer — создание текстов и документации
   - analyst — анализ данных и выявление паттернов
   - critic — проверка качества и выявление проблем
   - reviewer — code review и проверка материалов

## Формат ответа:

### 📋 Резюме задачи
(1-2 предложения: что нужно сделать и зачем)

### 🎯 Цель и критерии успеха
- Цель: ...
- Критерии успеха:
  - [ ] Критерий 1
  - [ ] Критерий 2

### ⚠️ Риски и ограничения
- Риск 1 → стратегия минимизации
- Риск 2 → стратегия минимизации

### 📝 План выполнения

#### Фаза 1: [Название фазы]
**Задача 1.1:** [Название] (P0, ~1 час)
- **Описание:** Что именно нужно сделать
- **Критерии завершения:** Как понять, что задача выполнена
- **Агент:** researcher / writer / analyst / critic / reviewer
- **Входные данные:** Что нужно для начала работы
- **Выходные данные:** Что получится в результате
- **Зависимости:** От каких задач зависит

**Задача 1.2:** [Название] (P1, ~30 мин)
- ...

#### Фаза 2: [Название фазы]
- ...

### 🔗 Карта зависимостей

- Задача 1.1 → Задача 2.1
- Задача 1.2 → Задача 2.1
- Задача 2.1 → Задача 2.2 → Задача 3.1

### ⏱️ Оценка сроков
- Общее время: ~X часов
- Критический путь: Задача 1.1 → 2.1 → 2.2 → 3.1 (~Y часов)
- Параллельное выполнение: можно запустить одновременно [список]

### ✅ Итоговые рекомендации
1. Начать с [задача] — это разблокирует остальные
2. Избегать [антипаттерн] — это приведёт к проблемам
3. Контрольная точка: после [фаза] пересмотреть план

## Принципы работы:

- Будь конкретным и практичным — избегай абстракций
- Каждая подзадача должна быть проверяемой
- Учитывай реальные ограничения (время, ресурсы, знания)
- Предусматривай план Б для критических задач
- Отвечай на русском языке
- Используй markdown для структурирования"""

    def __init__(
        self,
        name: str = "Planner",
        system_prompt: str | None = None,
    ):
        """Инициализация агента-планировщика.
        
        Args:
            name: Имя агента (по умолчанию "Planner")
            system_prompt: Кастомный system prompt.
                Если None, используется DEFAULT_SYSTEM_PROMPT.
        """
        super().__init__(
            name=name,
            system_prompt=system_prompt or self.DEFAULT_SYSTEM_PROMPT,
        )


__all__ = ["PlannerAgent"]