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

---

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

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

---

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

```mermaid
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

```mermaid
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 реализуют прикладную логику и контроль качества**.

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