# 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*