에이전트 런타임 분석 산출물 생성 (runtime-analysis-001)
This commit is contained in:
parent
5c11998668
commit
c6c260314b
1 changed files with 212 additions and 0 deletions
212
runtime-analysis/SPECIFICATION.md
Normal file
212
runtime-analysis/SPECIFICATION.md
Normal file
|
|
@ -0,0 +1,212 @@
|
||||||
|
# Agent Runtime Specification
|
||||||
|
|
||||||
|
## 1. MiniMax Connection Specification
|
||||||
|
|
||||||
|
### 1.1 Connection Pool
|
||||||
|
|
||||||
|
| Property | Specification |
|
||||||
|
|----------|---------------|
|
||||||
|
| Pool Size | Configurable, default 100 |
|
||||||
|
| Connection Timeout | 30 seconds |
|
||||||
|
| Keep-Alive | Enabled by default |
|
||||||
|
| Idle Timeout | 60 seconds |
|
||||||
|
| Max Routes Per Route | 50 |
|
||||||
|
|
||||||
|
### 1.2 Request Format
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"model": "string (required)",
|
||||||
|
"messages": [
|
||||||
|
{
|
||||||
|
"role": "string (required)",
|
||||||
|
"content": "string (required)"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"temperature": "number (0-2, optional)",
|
||||||
|
"max_tokens": "integer (optional)",
|
||||||
|
"stream": "boolean (optional, default false)"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.3 Response Format
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "string",
|
||||||
|
"model": "string",
|
||||||
|
"choices": [
|
||||||
|
{
|
||||||
|
"index": "integer",
|
||||||
|
"message": {
|
||||||
|
"role": "string",
|
||||||
|
"content": "string"
|
||||||
|
},
|
||||||
|
"finish_reason": "string"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"usage": {
|
||||||
|
"prompt_tokens": "integer",
|
||||||
|
"completion_tokens": "integer",
|
||||||
|
"total_tokens": "integer"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Output Contract Specification
|
||||||
|
|
||||||
|
### 2.1 Contract Version 1.0
|
||||||
|
|
||||||
|
| Field | Type | Required | Constraints |
|
||||||
|
|-------|------|----------|-------------|
|
||||||
|
| `content` | string | Yes | 0 ≤ length ≤ 128000 |
|
||||||
|
| `model` | string | Yes | Non-empty |
|
||||||
|
| `usage` | object | Yes | Contains prompt_tokens, completion_tokens, total_tokens |
|
||||||
|
| `finish_reason` | enum | Yes | One of: stop, length, content_filter, tool_calls |
|
||||||
|
| `tool_calls` | array | No | Array of tool call objects |
|
||||||
|
| `citations` | array | No | Array of citation objects |
|
||||||
|
| `metadata` | object | No | Arbitrary key-value pairs |
|
||||||
|
|
||||||
|
### 2.2 Validation Rules
|
||||||
|
|
||||||
|
1. **Schema Validation**: All required fields must be present
|
||||||
|
2. **Type Validation**: Field types must match specification
|
||||||
|
3. **Range Validation**: Numeric values within bounds
|
||||||
|
4. **Enum Validation**: Enumerated values from allowed set
|
||||||
|
|
||||||
|
### 2.3 Validation Error Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": {
|
||||||
|
"code": "CONTRACT_VIOLATION",
|
||||||
|
"message": "string",
|
||||||
|
"violations": [
|
||||||
|
{
|
||||||
|
"field": "string",
|
||||||
|
"expected": "string",
|
||||||
|
"actual": "string"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Retry Mechanism Specification
|
||||||
|
|
||||||
|
### 3.1 Retry Policy
|
||||||
|
|
||||||
|
| Condition | Action |
|
||||||
|
|-----------|--------|
|
||||||
|
| Network timeout | Retry |
|
||||||
|
| HTTP 408 | Retry |
|
||||||
|
| HTTP 429 | Retry with longer backoff |
|
||||||
|
| HTTP 5xx | Retry |
|
||||||
|
| HTTP 400 | Do not retry |
|
||||||
|
| HTTP 401 | Do not retry |
|
||||||
|
| HTTP 403 | Do not retry |
|
||||||
|
| Validation error | Do not retry |
|
||||||
|
|
||||||
|
### 3.2 Backoff Algorithm
|
||||||
|
|
||||||
|
```
|
||||||
|
delay = min(initial_delay * (multiplier ^ attempt) + jitter, max_delay)
|
||||||
|
|
||||||
|
where:
|
||||||
|
initial_delay = 1000ms
|
||||||
|
multiplier = 2.0
|
||||||
|
jitter = random(-10%, +10%)
|
||||||
|
max_delay = 30000ms
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 Circuit Breaker States
|
||||||
|
|
||||||
|
| State | Condition | Behavior |
|
||||||
|
|-------|-----------|----------|
|
||||||
|
| CLOSED | Normal operation | All requests pass |
|
||||||
|
| OPEN | Failure rate > 50% in 10s | All requests fail fast |
|
||||||
|
| HALF_OPEN | After 10s in OPEN | Allow 5 test requests |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Observation Points Specification
|
||||||
|
|
||||||
|
### 4.1 Trace Spans
|
||||||
|
|
||||||
|
| Span Name | Parent | Attributes |
|
||||||
|
|-----------|--------|------------|
|
||||||
|
| `agent-runtime-request` | Root | request_id, model |
|
||||||
|
| `connection-acquire` | agent-runtime-request | pool_name, wait_time |
|
||||||
|
| `request-build` | agent-runtime-request | payload_size |
|
||||||
|
| `api-call` | agent-runtime-request | endpoint, status_code |
|
||||||
|
| `retry-attempt-N` | api-call | attempt_num, error |
|
||||||
|
| `response-parse` | agent-runtime-request | response_size |
|
||||||
|
| `contract-validate` | agent-runtime-request | result, violations |
|
||||||
|
| `response-emit` | agent-runtime-request | output_size |
|
||||||
|
|
||||||
|
### 4.2 Metrics
|
||||||
|
|
||||||
|
| Metric | Type | Labels | Description |
|
||||||
|
|--------|------|--------|-------------|
|
||||||
|
| `runtime_requests_total` | Counter | model, status | Total requests |
|
||||||
|
| `runtime_request_duration_seconds` | Histogram | model | Request latency |
|
||||||
|
| `runtime_connections_active` | Gauge | pool_name | Active connections |
|
||||||
|
| `runtime_connections_wait_seconds` | Histogram | pool_name | Wait time |
|
||||||
|
| `runtime_retries_total` | Counter | model, error_type | Retry count |
|
||||||
|
| `runtime_contract_validations_total` | Counter | result | Validation count |
|
||||||
|
| `runtime_circuit_breaker_state` | Gauge | circuit_name | CB state (0/1/2) |
|
||||||
|
|
||||||
|
### 4.3 Log Events
|
||||||
|
|
||||||
|
| Event | Level | Fields |
|
||||||
|
|-------|-------|--------|
|
||||||
|
| `request_initiated` | INFO | request_id, model, timestamp |
|
||||||
|
| `request_completed` | INFO | request_id, duration_ms, tokens_used |
|
||||||
|
| `request_failed` | ERROR | request_id, error_code, error_message |
|
||||||
|
| `retry_triggered` | WARN | request_id, attempt, error_type, delay_ms |
|
||||||
|
| `circuit_opened` | ERROR | circuit_name, failure_rate |
|
||||||
|
| `circuit_closed` | INFO | circuit_name |
|
||||||
|
| `contract_violation` | ERROR | request_id, violations[] |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Integration Contract
|
||||||
|
|
||||||
|
### 5.1 Component Dependencies
|
||||||
|
|
||||||
|
```
|
||||||
|
Client
|
||||||
|
└── AgentRuntime
|
||||||
|
├── MiniMaxConnector
|
||||||
|
│ └── ConnectionPool
|
||||||
|
├── OutputContract
|
||||||
|
│ ├── SchemaValidator
|
||||||
|
│ └── TypeCoercer
|
||||||
|
├── RetryMechanism
|
||||||
|
│ ├── RetryPolicy
|
||||||
|
│ ├── BackoffCalculator
|
||||||
|
│ └── CircuitBreaker
|
||||||
|
└── Observability
|
||||||
|
├── Tracer
|
||||||
|
├── MetricsCollector
|
||||||
|
└── LogEmitter
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 Error Propagation
|
||||||
|
|
||||||
|
| Source | Error Type | Propagation |
|
||||||
|
|--------|------------|-------------|
|
||||||
|
| MiniMaxConnector | ConnectionError | RetryMechanism |
|
||||||
|
| MiniMaxConnector | TimeoutError | RetryMechanism |
|
||||||
|
| MiniMaxConnector | AuthError | Client (no retry) |
|
||||||
|
| OutputContract | ValidationError | Client (no retry) |
|
||||||
|
| CircuitBreaker | OpenError | Client (no retry) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Specification Version: 1.0*
|
||||||
|
*Last Updated: 2026-07-10*
|
||||||
Loading…
Add table
Add a link
Reference in a new issue