165 lines
6.8 KiB
Markdown
165 lines
6.8 KiB
Markdown
# Agent Runtime Specification
|
|
|
|
## 1. 개요
|
|
|
|
본 문서는 Agent Runtime의 컴포넌트 구조, 의존성, 메트릭 명명 규칙을 정의한다.
|
|
|
|
## 2. 컴포넌트 의존성 다이어그램
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Agent Runtime │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ MiniMaxConnector │────▶│ ConnectionPool │ │
|
|
│ └────────┬────────┘ └─────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ RetryHandler │ │ CircuitBreaker │ │
|
|
│ └─────────────────┘ └─────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ HealthChecker │────▶│ MetricsCollector│ │
|
|
│ └─────────────────┘ └─────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────┐ │
|
|
│ │ ContractEmitter │ │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 3. 컴포넌트 정의
|
|
|
|
### 3.1 MiniMaxConnector
|
|
|
|
| 속성 | 값 |
|
|
|------|-----|
|
|
| 타입 | connector |
|
|
| 설명 | MiniMax API와의 HTTP/WebSocket 연결 관리 |
|
|
| 의존성 | ConnectionPool, RetryHandler |
|
|
|
|
### 3.2 ConnectionPool
|
|
|
|
| 속성 | 값 |
|
|
|------|-----|
|
|
| 타입 | pool |
|
|
| 설명 | 연결 풀링 및 리소스 관리 |
|
|
| 의존성 | 없음 |
|
|
|
|
### 3.3 RetryHandler
|
|
|
|
| 속성 | 값 |
|
|
|------|-----|
|
|
| 타입 | handler |
|
|
| 설명 | 재시도 정책 및 지연 관리 |
|
|
| 의존성 | 없음 |
|
|
|
|
### 3.4 CircuitBreaker
|
|
|
|
| 속성 | 값 |
|
|
|------|-----|
|
|
| 타입 | protection |
|
|
| 설명 | 서킷 브레이커 상태 관리 |
|
|
| 의존성 | MiniMaxConnector |
|
|
|
|
### 3.5 HealthChecker
|
|
|
|
| 속성 | 값 |
|
|
|------|-----|
|
|
| 타입 | monitor |
|
|
| 설명 | 연결 상태 모니터링 및 헬스 체크 |
|
|
| 의존성 | MetricsCollector |
|
|
|
|
### 3.6 ContractEmitter
|
|
|
|
| 속성 | 값 |
|
|
|------|-----|
|
|
| 타입 | validator |
|
|
| 설명 | 출력 계약 검증 및 에미터 |
|
|
| 의존성 | 없음 |
|
|
|
|
## 4. 메트릭 명명 규칙
|
|
|
|
### 4.1 명명 체계
|
|
|
|
모든 메트릭은 **dot-notation** 형식을 사용한다:
|
|
|
|
```
|
|
{domain}.{subdomain}.{name}
|
|
```
|
|
|
|
### 4.2 도메인 분류
|
|
|
|
| 도메인 | 설명 | 예시 |
|
|
|--------|------|------|
|
|
| request | 요청 관련 | request.start, request.duration |
|
|
| connection | 연결 관련 | connection.acquired, connection.wait_time |
|
|
| retry | 재시도 관련 | retry.attempt, retry.success |
|
|
| contract | 계약 관련 | contract.validation |
|
|
| circuit | 서킷 브레이커 관련 | circuit.state, circuit.transitions |
|
|
| health | 헬스 체크 관련 | health.status |
|
|
|
|
### 4.3 메트릭 정의
|
|
|
|
| 메트릭명 | 타입 | 라벨 | 설명 |
|
|
|----------|------|------|------|
|
|
| request.start | Counter | endpoint, method | API 요청 시작 카운터 |
|
|
| request.duration | Histogram | endpoint, status | API 요청 소요 시간 |
|
|
| connection.acquired | Gauge | pool_name | 현재 획득된 연결 수 |
|
|
| connection.wait_time | Histogram | pool_name | 연결 대기 시간 |
|
|
| connection.released | Gauge | pool_name | 반환된 연결 수 |
|
|
| retry.attempt | Counter | endpoint, error_type | 재시도 발생 횟수 |
|
|
| retry.success | Counter | endpoint | 재시도 후 성공 횟수 |
|
|
| retry.exhausted | Counter | endpoint | 재시도 횟수 소진 횟수 |
|
|
| contract.validation | Counter | schema_version, result | 계약 검증 결과 카운터 |
|
|
| circuit.state | Gauge | endpoint | 서킷 브레이커 상태 |
|
|
| circuit.transitions | Counter | from_state, to_state | 서킷 브레이커 상태 전이 횟수 |
|
|
| circuit.rejected | Counter | endpoint | 차단된 요청 수 |
|
|
| health.status | Gauge | component | 컴포넌트 헬스 상태 |
|
|
|
|
## 5. 관측 가능성 (Observability)
|
|
|
|
### 5.1 관측 컴포넌트
|
|
|
|
| 컴포넌트 | 설명 | 수집 데이터 |
|
|
|----------|------|-------------|
|
|
| Tracer | 분산 추적 수집기 | request.start, connection.acquired, contract.validation |
|
|
| MetricsCollector | 메트릭 수집 및 집계 | request.*, connection.*, retry.*, contract.*, circuit.*, health.* |
|
|
| LogEmitter | 로그 출력 | request.start, retry.attempt, contract.validation |
|
|
| AlertManager | 알림 및 경고 관리 | circuit.state, retry.exhausted, health.status |
|
|
|
|
### 5.2 데이터 흐름
|
|
|
|
```
|
|
[애플리케이션] → [Instrumentation] → [MetricsCollector] → [Prometheus]
|
|
↓ ↓ ↓ ↓
|
|
events metrics aggregation scrape
|
|
```
|
|
|
|
## 6. 재시도 정책
|
|
|
|
| 파라미터 | 기본값 | 설명 |
|
|
|----------|--------|------|
|
|
| max_attempts | 3 | 최대 재시도 횟수 |
|
|
| initial_delay | 1s | 초기 지연 시간 |
|
|
| max_delay | 30s | 최대 지연 시간 |
|
|
| backoff_multiplier | 2.0 | 지연 증가 배율 |
|
|
| jitter | true | 랜덤 지터 적용 |
|
|
|
|
## 7. 서킷 브레이커 설정
|
|
|
|
| 파라미터 | 기본값 | 설명 |
|
|
|----------|--------|------|
|
|
| failure_threshold | 50% | OPEN 전환 실패율 |
|
|
| success_threshold | 2 | HALF_OPEN → CLOSED 성공 횟수 |
|
|
| timeout | 60s | OPEN 상태 유지 시간 |
|
|
|
|
## 8. 버전 정보
|
|
|
|
| 항목 | 값 |
|
|
|------|-----|
|
|
| 스키마 버전 | 1.0.0 |
|
|
| 문서 업데이트 | 2026-07-10 |
|