agent/_process/02. Agent architecture.md

Ниже обновленная версия с учетом гибридной модели интент роутера.

---

1. Концепция агента

Агент проектируется как intent-driven система для работы с кодом и документацией, где пользовательский запрос сначала нормализуется и интерпретируется, затем по нему извлекается релевантный контекст из многослойного RAG, после чего специализированный task workflow выполняет целевую задачу. Агент не является единым “умным чатом”: логика разделена на маршрутизацию, retrieval и специализированные execution workflows. Проверка evidence, вызовы LLM и правила сборки ответа находятся внутри task workflows и зависят от типа задачи.

---

2. Компонентная модель

flowchart LR
    IDE[IDE Plugin / Client] --> API[API Layer]
    API --> IR[IntentRouter V3]
    IR --> RAG[Retrieval RAG]

    RAG --> TW1[Task Workflow: Documentation Explain]
    RAG --> TW2[Task Workflow: OpenAPI Generation]
    RAG --> TW3[Task Workflow: Documentation Generation]
    RAG --> TWN[Other Specialized Task Workflows]

    TW1 --> OUT[Response / Artifact]
    TW2 --> OUT
    TW3 --> OUT
    TWN --> OUT

---

3. Основной flow процесса

Основной процесс

1. Пользователь отправляет запрос через IDE plugin или другой клиент.

2. API Layer принимает запрос и передает его в агент.

3. IntentRouter V3:

   • нормализует запрос;
   • детерминированно извлекает ключевые артефакты;
   • с помощью LLM определяет тип задачи и параметры обработки;
   • формирует параметры retrieval.

4. Выполняется извлечение данных из Retrieval RAG.

5. Извлеченный контекст передается в соответствующий Task Workflow.

6. Внутри workflow выполняется:

   • подготовка контекста;
   • evidence-проверки;
   • вызовы LLM;
   • формирование результата.

7. Результат возвращается пользователю.

Sequence diagram

sequenceDiagram
    participant User as User / IDE Plugin
    participant API as API Layer
    participant Router as IntentRouter V3
    participant RAG as Retrieval RAG
    participant WF as Task Workflow

    User->>API: request
    API->>Router: agent call
    Router->>Router: normalize + extract artifacts
    Router->>Router: LLM routing (task / intent)
    Router->>RAG: retrieval request
    RAG-->>Router: retrieved context
    Router->>WF: route result + context
    WF->>WF: evidence logic + LLM calls
    WF-->>API: final result
    API-->>User: response

---

4. Описание компонентов

4.1. IDE Plugin / Client

Задача Точка входа пользователя в агент.

Как устроен Любой внешний клиент (IDE plugin, web UI и др.), который отправляет запрос и получает результат.

Почему так Агент изначально проектируется как backend-система, независимая от интерфейса.

---

4.2. API Layer

Задача Обеспечивает внешний интерфейс взаимодействия с агентом.

Как устроен Принимает запрос, валидирует его и передает во внутренний pipeline, затем возвращает результат.

Почему так Позволяет изолировать транспортный слой от логики агента.

---

4.3. IntentRouter V3

Задача Определяет, как должен обрабатываться пользовательский запрос и какой сценарий выполнения применить.

Как устроен

Гибридная модель из двух частей:

1. Детерминированный слой

Выполняет:

• нормализацию запроса;

• извлечение ключевых артефактов:

  • домены;
  • типы сущностей (API, entity, component и т.д.);
  • явные ссылки (endpoint, путь, имя);

• выделение базовых сигналов (например: explain / list / generate).

Этот слой задает жесткие рамки интерпретации запроса.

2. LLM-роутинг

Использует:

• нормализованный запрос;
• извлеченные артефакты;
• описание доступных типов задач;

и определяет:

• тип задачи;
• общий сценарий обработки;
• параметры retrieval;
• ожидаемую форму ответа.

Итог

Router формирует:

• параметры retrieval;
• тип task workflow;
• контекст для дальнейшего выполнения.

Почему решение такое

Ранее использовался более детерминированный подход с фиксированными сценариями, который хорошо работал в узком наборе задач, но плохо масштабируется. Полностью LLM-based роутинг, наоборот, дает гибкость, но теряет предсказуемость и управляемость.

Поэтому выбран гибридный подход:

• детерминированный слой фиксирует ключевые артефакты и ограничения;
• LLM выполняет гибкую интерпретацию задачи.

Это позволяет:

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

---

4.4. Retrieval RAG

Задача Извлечь релевантный контекст для выполнения задачи.

Как устроен Многослойная система хранения знаний (код, документация, факты, связи), из которой извлекается структурированный контекст в зависимости от параметров, заданных роутером.

Почему так Разные задачи требуют разных типов данных, поэтому используется слойная модель вместо плоского поиска.

---

4.5. Task Workflows

Задача Реализуют прикладную логику выполнения конкретного типа задачи.

Как устроены Набор специализированных workflows, например:

• объяснение по документации;
• генерация OpenAPI;
• генерация документации;
• другие сценарии.

Внутри workflow находятся:

• обработка контекста;
• evidence-проверки;
• вызовы LLM;
• сборка результата.

Почему так Логика проверки данных и генерации сильно зависит от задачи, поэтому она инкапсулируется в отдельных workflows, а не в одном универсальном слое.

---

4.6. Output / Artifact

Задача Вернуть результат пользователю.

Как устроен Может быть:

• текстовый ответ;
• структурированный список;
• OpenAPI спецификация;
• документация;
• иной артефакт.

Почему так Агент должен поддерживать не только ответы, но и генерацию инженерных артефактов.

---

Итог

Обновленная архитектура строится на следующем принципе:

• детерминированное извлечение ключевых артефактов задает рамки;
• LLM выполняет гибкий роутинг внутри этих рамок;
• retrieval обеспечивает данные;
• task workflows реализуют прикладную логику и контроль качества.

Это позволяет одновременно сохранить управляемость системы и обеспечить масштабируемость под новые типы задач.