# AgentEngine Architecture Document
> **Version:** v2.61.0 | **Last Updated:** 2026-05-04 | **Author:** ConnectAI Lab

---

## 1. Overview (설계 개요)

`AgentEngine`은 ConnectAI(Astra) 확장의 핵심 실행 엔진으로, **Producer-Consumer 패턴** 기반의 멀티 에이전트 오케스트레이션을 담당합니다. Planner → Researcher → Writer의 3단계 파이프라인을 통해 사용자의 자연어 요청을 전략 수립, 정보 수집, 최종 보고서 작성이라는 전문화된 단계로 분할 처리합니다.

### 핵심 설계 원칙

| 원칙 | 구현 |
|---|---|
| **의존성 주입 (DI)** | `IAgent` 인터페이스를 통해 에이전트를 런타임에 교체 가능 |
| **명시적 동시성 제어** | `LockManager`(Mutex) + `ActionQueueManager`(Concurrency Limit) |
| **복원력 우선 (Resilience-First)** | `ErrorRecoveryMatrix`를 통한 오류 자동 분류 및 복구 |
| **투명한 상태 관리** | `MissionState`를 통한 감사 이력(Audit Trail) 자동 기록 |

---

## 2. Architecture Diagram (아키텍처 다이어그램)

```
┌──────────────────────────────────────────────────────────────┐
│                    AgentWorkflowManager                      │
│                   (Public Entry Point)                        │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                       AgentEngine                             │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  1. LockManager.acquire()  ← Mutex (동일 미션 중복 방지) │ │
│  │  2. ActionQueue.enqueue()  ← Concurrency Limit (≤3)     │ │
│  │  3. resilientExecute()     ← Error Recovery Matrix      │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌──────────┐   ┌──────────────┐   ┌────────────┐           │
│  │ Planner  │──▶│  Researcher  │──▶│   Writer   │           │
│  │ (IAgent) │   │   (IAgent)   │   │  (IAgent)  │           │
│  └──────────┘   └──────┬───────┘   └────────────┘           │
│                        │                                     │
│                 ┌──────┴───────┐                             │
│                 │ WriterPrep   │  ← Promise.all() 병렬 실행   │
│                 │ (Parallel)   │                              │
│                 └──────────────┘                             │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │              MissionState (Audit Trail)                  │ │
│  │  idle → planner → researcher → writer → completed       │ │
│  │  [toStructuredLog()] → JSON 출력 → 모니터링 대시보드     │ │
│  └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```

---

## 3. Lock Management (락 관리)

### 3.1 LockManager (Mutex)

**파일:** `src/core/lock.ts`

**설계 의도:** 동일한 `missionId`에 대한 중복 실행을 방지합니다. 예를 들어, 사용자가 동일한 질문을 빠르게 두 번 전송한 경우, 두 번째 요청은 첫 번째 요청이 완료될 때까지 대기합니다.

**동작 원리:**
```
Mission A (id: "abc") 시작 → Lock 획득 ✅
Mission B (id: "abc") 시작 → Lock 대기 ⏳ (Mission A 완료까지)
Mission A 완료 → Lock 해제 → Mission B Lock 획득 ✅
```

**핵심 보장:**
- 동일 미션 ID의 순차 실행 보장 (Race Condition 방지)
- `finally` 블록에서 반드시 `release()` 호출 → 데드락 불가

### 3.2 ActionQueueManager (동시성 제어)

**파일:** `src/core/queue.ts`

**설계 의도:** 시스템 전체에서 동시에 실행되는 에이전트 작업 수를 제한하여 리소스 고갈을 방지합니다.

**핵심 파라미터:**

| 파라미터 | 기본값 | 설명 |
|---|---|---|
| `concurrencyLimit` | 3 | 동시 실행 가능한 최대 작업 수 |
| `activeCount` | - | 현재 실행 중인 작업 수 (동적) |
| micro-delay | 10ms | 작업 간 시스템 호흡 시간 |

**Mutex vs Queue의 역할 분리:**

| 구분 | LockManager | ActionQueueManager |
|---|---|---|
| 범위 | 미션 단위 (단일 ID) | 시스템 전체 |
| 목적 | 중복 실행 방지 | 리소스 포화 방지 |
| 방식 | 독점 잠금 (Exclusive) | 동시성 제한 (Bounded) |

---

## 4. Error Recovery Matrix (오류 복구 매트릭스)

### 4.1 오류 분류 체계

`ErrorClassifier`는 에러 객체의 `name`과 `message`를 정규식 패턴 매칭하여 세 범주로 자동 분류합니다.

```
┌──────────────┬──────────┬──────────────┬─────────────────────────────────┐
│ Error Type   │ Retries  │ Backoff      │ Action                         │
├──────────────┼──────────┼──────────────┼─────────────────────────────────┤
│ TRANSIENT    │ 3        │ Exponential  │ 자동 재시도 (1s → 2s → 4s)      │
│              │          │ (1000ms)     │                                 │
├──────────────┼──────────┼──────────────┼─────────────────────────────────┤
│ PERMANENT    │ 0        │ N/A          │ 즉시 중단 + 사용자 안내 메시지    │
├──────────────┼──────────┼──────────────┼─────────────────────────────────┤
│ ABORT        │ 0        │ N/A          │ Graceful Exit (조용한 종료)      │
└──────────────┴──────────┴──────────────┴─────────────────────────────────┘
```

### 4.2 분류 패턴 목록

**Transient (재시도 가능):**
- `ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `ENOTFOUND`
- `timeout`, `network`, `fetch failed`, `Failed to fetch`
- HTTP `502`, `503`, `429`
- `socket hang up`

**Permanent (즉시 중단):**
- HTTP `401`, `403`, `404`
- `유효한 응답을 받지 못했습니다` (내부 검증 실패)
- `Ollama URL이 설정되지 않았습니다` (설정 누락)
- `invalid model`, `model not found` (모델 문제)

**분류 불가 → Permanent (보수적 처리):**
- 알려지지 않은 오류는 안전하게 Permanent로 분류하여 무한 재시도를 방지

### 4.3 resilientExecute 실행 흐름

```
resilientExecute(agent, ...)
    │
    ├─ attempt 0: agent.execute()
    │   ├─ 성공 → return result
    │   └─ 실패 → ErrorClassifier.classify(error)
    │       ├─ ABORT     → throw (즉시 전파)
    │       ├─ PERMANENT → throw (사용자 메시지 첨부)
    │       └─ TRANSIENT → continue
    │
    ├─ attempt 1: wait 1000ms → agent.execute()
    │   └─ (동일 분기)
    │
    ├─ attempt 2: wait 2000ms → agent.execute()
    │   └─ (동일 분기)
    │
    └─ attempt 3: wait 4000ms → agent.execute()
        └─ 실패 시 → "재시도 소진" 에러 throw
```

---

## 5. MissionState & Monitoring (상태 관리 및 모니터링)

### 5.1 MissionState 설계 의도

엔진 내부의 상태(`this.stage`)를 독립 객체로 분리하여:
1. **감사 이력(Audit Trail)** 자동 기록: 모든 상태 전환이 타임스탬프, 소요 시간과 함께 기록됨
2. **외부 노출**: `getMissionState()`를 통해 외부 모니터링 시스템이 실시간 상태를 읽을 수 있음
3. **디버깅 지원**: 에러 발생 시 `summarizeAudit()`로 전체 전환 이력을 한 줄로 덤프

### 5.2 toStructuredLog() 출력 포맷

```json
{
    "missionId": "mission_1714832400000",
    "status": "completed",
    "startTime": "2026-05-04T02:40:00.000Z",
    "totalElapsedMs": 12450,
    "transitionCount": 4,
    "transitions": [
        {
            "from": "idle",
            "to": "planner",
            "durationMs": 0,
            "message": "전략 수립 중...",
            "ts": "2026-05-04T02:40:00.000Z"
        },
        {
            "from": "planner",
            "to": "researcher",
            "durationMs": 3200,
            "message": "핵심 정보 수집 및 분석 중...",
            "ts": "2026-05-04T02:40:03.200Z"
        }
    ]
}
```

이 포맷은 ELK Stack, Loki, Datadog 등의 외부 시스템에 파싱 없이 직접 인제스트할 수 있습니다.

### 5.3 Mission Control Dashboard

**파일:** `assets/mission_control.html`

`toStructuredLog()`의 JSON 출력을 브라우저에서 시각화하는 독립형 대시보드입니다.
- 에이전트 타임라인 시각화
- 단계별 지연 시간(Latency) 표시
- 미션 상태 및 효율성 분석 지표 제공

---

## 6. IAgent Interface (에이전트 인터페이스)

### 6.1 기본 시그니처

```typescript
interface IAgent {
    execute(
        input: string,
        context?: string,
        signal?: AbortSignal,
        options?: AgentExecuteOptions
    ): Promise<string>;
}
```

### 6.2 AgentExecuteOptions (확장 옵션)

| 필드 | 타입 | 용도 |
|---|---|---|
| `context` | `string` | 추가 컨텍스트 |
| `signal` | `AbortSignal` | 중단 시그널 |
| `config` | `Record<string, unknown>` | 에이전트별 커스텀 설정 (temperature, maxTokens 등) |
| `priorResults` | `Record<string, string>` | 이전 단계 중간 결과물 (병렬 파이프라인용) |

**확장 전략:** 새로운 에이전트가 추가될 때 `options.config`에 자유롭게 설정을 넣을 수 있으므로, `IAgent` 시그니처를 변경할 필요가 없습니다.

---

## 7. Test & Benchmark Coverage (테스트 커버리지)

**파일:** `tests/agentEngine.test.ts` | **총 41개 테스트**

| Suite | Tests | Description |
|---|---|---|
| ErrorClassifier | 20 | Transient(10), Permanent(7), Abort(2), Unknown(1) 분류 정확성 |
| Recovery Matrix | 3 | 매트릭스 규칙 정합성 |
| MissionState | 4 | 상태 전환, Audit Trail, JSON 포맷 |
| Engine Integration | 6 | 정상/재시도/즉시중단/취소/재시도소진/상태정리 |
| Performance | 3 | 정상 Latency, 재시도 오버헤드, 즉시 중단 시간 |
| Concurrency & Stress | 4 | 병렬 실행, 혼합 오류, 큐 포화, Race Condition |

### 벤치마크 기준치

| Metric | Measured | Threshold |
|---|---|---|
| Normal Mission Avg Latency | 165ms | < 1,000ms |
| Retry Overhead (2 retries) | 3,012ms | 2,500–10,000ms |
| Permanent Fail Time | 11ms | < 500ms |
| 5 Concurrent Missions | 23ms | < 30,000ms |
| Queue Saturation (10 tasks) | 44ms | all complete |

### 배포 게이트

```json
"vscode:prepublish": "npm run test && npm run compile"
```

모든 41개 테스트가 통과해야만 `.vsix` 패키징이 진행됩니다.

---

## 8. File Map (파일 맵)

```
src/
├── lib/
│   └── engine.ts          ← AgentEngine, MissionState, ErrorClassifier,
│                             ErrorRecoveryMatrix, IAgent, AgentExecuteOptions
├── core/
│   ├── queue.ts           ← ActionQueueManager (Concurrency Limit)
│   └── lock.ts            ← LockManager (Mutex)
├── agents/
│   ├── factory.ts         ← PlannerAgent, ResearcherAgent, WriterAgent (BaseAgent)
│   └── AgentWorkflowManager.ts ← Public API (runStrictWorkflow)
└── utils.ts               ← logInfo, logError, logWarn (→ VS Code Output Channel "Astra")

tests/
└── agentEngine.test.ts    ← 41 integration tests + benchmarks

assets/
└── mission_control.html   ← Mission Control Dashboard (standalone)
```

---

## 9. Maintenance Notes (유지보수 참고)

### 새 에이전트 추가 시

1. `IAgent`를 구현하는 새 클래스를 `factory.ts`에 추가
2. `AgentEngine` 생성자에 주입 (DI)
3. `PipelineStage` 타입에 새 단계 추가
4. `AgentWorkflowManager.mapStageToUI()`에 UI 매핑 추가

### 새 오류 패턴 추가 시

1. `ErrorClassifier.TRANSIENT_PATTERNS` 또는 `PERMANENT_PATTERNS`에 정규식 추가
2. `tests/agentEngine.test.ts`의 해당 describe 블록에 테스트 케이스 추가
3. `npm run test:engine`으로 검증

### 동시성 제한 변경 시

`src/core/queue.ts`의 `new ActionQueueManager(N)` 생성자 인자를 조정합니다.
기본값은 3이며, 리소스 여유에 따라 조정 가능합니다.
