agent/app/modules/agent

Модуль agent

1. Функции модуля

• Оркестрация выполнения пользовательского запроса поверх роутера интентов и графов.
• Формирование TaskSpec, запуск оркестратора шагов и сборка финального результата.
• Реализация необходимых для агента tools и их интеграция с остальной логикой выполнения.
• Сохранение quality-метрик и session-артефактов для последующей привязки к Story.

2. Диаграмма классов и взаимосвязей

classDiagram
    class AgentModule
    class GraphAgentRuntime
    class OrchestratorService
    class TaskSpecBuilder
    class StorySessionRecorder
    class StoryContextRepository
    class ConfluenceService
    class AgentRepository

    AgentModule --> GraphAgentRuntime
    AgentModule --> ConfluenceService
    AgentModule --> StorySessionRecorder
    StorySessionRecorder --> StoryContextRepository
    GraphAgentRuntime --> OrchestratorService
    GraphAgentRuntime --> TaskSpecBuilder
    GraphAgentRuntime --> AgentRepository
    GraphAgentRuntime --> ConfluenceService

3. Описание классов

• AgentModule: собирает runtime и публикует внутренние tools-роуты. Методы: __init__ — связывает зависимости модуля; internal_router — регистрирует internal API tools.
• GraphAgentRuntime: основной исполнитель агентного запроса. Методы: run — выполняет цикл route -> retrieval -> orchestration -> ответ/changeset.
• OrchestratorService: управляет планом шагов и выполнением quality gates. Методы: run — строит, валидирует и исполняет execution plan.
• TaskSpecBuilder: формирует спецификацию задачи для оркестратора. Методы: build — собирает TaskSpec из route, контекстов и ограничений.
• StorySessionRecorder: пишет session-scoped артефакты для последующего bind к Story. Методы: record_run — сохраняет входные источники и выходные артефакты сессии.
• StoryContextRepository: репозиторий Story-контекста и его связей. Методы: record_story_commit — фиксирует commit-контекст Story; upsert_story — создает/обновляет карточку Story; add_session_artifact — добавляет session-артефакт; bind_session_to_story — переносит артефакты сессии в Story; add_artifact — добавляет версионный Story-артефакт; get_story_context — возвращает агрегированный контекст Story.
• ConfluenceService: tool для загрузки страницы по URL. Методы: fetch_page — валидирует URL и возвращает нормализованный payload страницы.
• AgentRepository: хранение router-контекста и quality-метрик. Методы: ensure_tables — создает таблицы модуля; get_router_context — читает контекст маршрутизации; update_router_context — обновляет историю диалога и last-route; save_quality_metrics — сохраняет метрики качества; get_quality_metrics — читает историю метрик.

4. Сиквенс-диаграммы API

POST /internal/tools/confluence/fetch

Назначение: загружает страницу Confluence по URL и возвращает ее контент для дальнейшего использования в сценариях агента.

sequenceDiagram
    participant Router as AgentModule.APIRouter
    participant Confluence as ConfluenceService

    Router->>Confluence: fetch_page(url)
    Confluence-->>Router: page(content_markdown, metadata)