에이전트 런타임 분석 산출물 생성 (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