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 |
