klg-asutk-app/docs/AUTONOMOUS_AGENT.md

# Autonomous Agent Architecture

## Обзор

Система эволюционирует от CRUD → Copilot → Autonomous Agent:

- **CRUD**: Традиционные операции создания, чтения, обновления, удаления
- **Copilot**: Ассистирование пользователю через естественный язык
- **Autonomous Agent**: Автономное выполнение задач на основе reasoning

## Архитектура

```
┌─────────────────────────────────────────────────────────┐
│              Natural Language Interface                   │
│         (Пользователь запрашивает "смыслом")              │
└──────────────────────┬────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│                  LLM Reasoning Engine                      │
│         (Рассуждения на основе Knowledge Graph)            │
└──────────────────────┬────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
        ▼              ▼              ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  Knowledge   │ │   Planning   │ │  Execution   │
│    Graph     │ │   (Plan)     │ │  (Actions)   │
└──────────────┘ └──────────────┘ └──────────────┘
```

## Компоненты

### 1. Knowledge Graph

**Назначение:** Преобразование данных в граф знаний

**Структура:**
- **Узлы**: Сущности (воздушные суда, аудиты, риски, операторы)
- **Рёбра**: Связи между сущностями
- **Embeddings**: Векторные представления для семантического поиска

**Пример:**
```typescript
import { buildKnowledgeGraph } from '@/lib/ai/knowledge-graph';

const graph = await buildKnowledgeGraph();
// graph.nodes - узлы графа
// graph.edges - связи между узлами
```

### 2. LLM Reasoning

**Назначение:** Рассуждения на основе Knowledge Graph

**Возможности:**
- Chain of Thought reasoning
- Анализ связей в графе
- Логические выводы
- Предложение действий

**Пример:**
```typescript
import { reasonWithKnowledgeGraph } from '@/lib/ai/llm-reasoning';

const reasoning = await reasonWithKnowledgeGraph(
  'Какие воздушные суда требуют внимания?'
);
// reasoning.answer - ответ
// reasoning.reasoning - шаги рассуждения
// reasoning.suggestedActions - предложенные действия
```

### 3. Natural Language Interface

**Назначение:** Интерфейс для взаимодействия через естественный язык

**Режимы:**
- **Copilot**: Ассистирование, предложение действий
- **Autonomous**: Автономное выполнение задач

**Пример:**
```typescript
import { processNaturalLanguageQuery } from '@/lib/ai/natural-language-interface';

// Copilot режим
const response = await processNaturalLanguageQuery({
  query: 'Покажи все активные воздушные суда оператора Аэрофлот',
  mode: 'copilot',
});

// Autonomous режим
const response = await processNaturalLanguageQuery({
  query: 'Создай новое воздушное судно RA-12345 типа Boeing 737',
  mode: 'autonomous',
});
```

### 4. Autonomous Agent

**Назначение:** Автономное выполнение задач

**Возможности:**
- Планирование действий
- Выполнение плана
- Анализ результатов
- Рекомендации

**Пример:**
```typescript
import { createAutonomousAgent } from '@/lib/ai/autonomous-agent';

const agent = createAutonomousAgent();

// Планирование
const plan = await agent.plan('Обнови статус всех воздушных судов');

// Выполнение
const result = await agent.execute(plan);
```

## Использование

### API Endpoints

#### POST `/api/ai/agent`

Обработка естественного языка запроса.

**Request:**
```json
{
  "query": "Покажи все активные воздушные суда",
  "mode": "copilot",
  "context": {}
}
```

**Response:**
```json
{
  "answer": "Найдено 15 активных воздушных судов...",
  "reasoning": ["Шаг 1: Поиск в базе данных...", "Шаг 2: Фильтрация по статусу..."],
  "actions": [
    {
      "type": "suggested",
      "description": "Показать детали каждого ВС",
      "executed": false
    }
  ],
  "confidence": 0.9,
  "mode": "copilot",
  "intent": {
    "intent": "query",
    "confidence": 0.95
  }
}
```

#### GET `/api/knowledge/graph`

Получение Knowledge Graph.

**Query Parameters:**
- `query` - поисковый запрос (опционально)
- `format` - формат ответа: `json` или `visualization`

**Response:**
```json
{
  "nodes": [
    {
      "id": "aircraft-1",
      "type": "aircraft",
      "label": "RA-12345",
      "properties": {...}
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": "aircraft-1",
      "target": "operator-Aeroflot",
      "type": "operated_by",
      "weight": 1.0
    }
  ]
}
```

## Примеры запросов

### Copilot режим

```
"Покажи все воздушные суда, которые требуют технического обслуживания"
"Какие риски связаны с воздушным судном RA-12345?"
"Дай рекомендации по улучшению безопасности"
```

### Autonomous режим

```
"Создай новое воздушное судно RA-12345 типа Boeing 737 для оператора Аэрофлот"
"Обнови статус всех воздушных судов оператора Аэрофлот на 'Активен'"
"Проанализируй все риски и создай отчёт"
```

## Эволюция системы

### CRUD (Текущее состояние)

- Пользователь кликает по кнопкам
- Выполняются стандартные операции
- Результат отображается в UI

### Copilot (Реализовано)

- Пользователь задаёт вопросы на естественном языке
- Система понимает намерение
- Предлагает действия
- Пользователь подтверждает выполнение

### Autonomous Agent (Реализовано)

- Пользователь описывает задачу
- Система планирует действия
- Автономно выполняет план
- Отчитывается о результатах

## Преимущества

1. **Естественное взаимодействие** - пользователь не кликает, а "запрашивает смыслом"
2. **Интеллектуальные рассуждения** - система понимает контекст и связи
3. **Автономность** - система может выполнять задачи самостоятельно
4. **Масштабируемость** - легко добавлять новые возможности через reasoning

## Безопасность

- Все действия логируются
- Пользователь может отменить выполнение
- Валидация перед выполнением критических операций
- Аудит всех действий агента

## Дополнительная информация

См. также:
- `docs/AI_KNOWLEDGE_SYSTEM.md` - Система знаний
- `docs/STREAMING_ARCHITECTURE.md` - Streaming архитектура