Agent Envelope Exchange
The universal message protocol for Quox. Every interaction, heartbeat, and agent communication wrapped in a standardized envelope for complete traceability.
AEE protocol explainer. 14 fields, full traceability, open specification.
Why AEE?
Before AEE, Quox faced critical gaps:
The 14-field envelope
Every AEE message contains these fields:
interface AEEEnvelope {
// Required (10 fields)
v: "1" // Protocol version
id: string // Unique message ID (ULID)
ts: string // ISO 8601 timestamp
type: "task" | "result" | "event" | "error" | "stream"
from: string // "human.adam", "agent.cipher"
to: string // "agent.quox", "mha.nw-web-01"
intent: string // "quox.chat.query"
corr: string // Correlation ID (conversation)
reply_to: string | null // Parent message ID
payload: object // Intent-specific data
// Optional (4 fields)
trace?: { trace_id, span_id }
priority?: "low" | "normal" | "high" | "urgent"
requires?: { timeout_ms?, evidence?, approval? }
sig?: string | null // Signature for verification
}Message types
Quox intents
Namespaced intents for routing and processing:
| Intent | Type | Description |
|---|---|---|
quox.chat.query | task | Human query to Quox |
quox.chat.response | result | Quox response to human |
quox.agent.delegate | task | Agent delegating to another |
mha.heartbeat.report | event | MHA agent heartbeat |
mha.job.submit | task | Submit job to MHA |
aee.capability.list | task | Discover agent capabilities |
Message flow
┌─────────────────────────────────────────────────────────┐
│ USER: "Check disk on nw-monitor-01" │
│ │
│ → AEE Envelope Created: │
│ id: "01JFB2QX..." │
│ type: "task" │
│ from: "human.adam" │
│ to: "agent.cipher" │
│ intent: "quox.chat.query" │
│ corr: "conv_abc123" ← NEW conversation │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ COLLECTOR → CLAUDE → RESPONSE │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ RESPONSE ENVELOPE: │
│ id: "01JFB2R7..." │
│ type: "result" │
│ from: "agent.cipher" │
│ to: "human.adam" │
│ corr: "conv_abc123" ← SAME conversation │
│ reply_to: "01JFB2QX..." ← Links to request │
└─────────────────────────────────────────────────────────┘
Storage architecture
📱 Primary: IndexedDB
- Browser-based storage
- Unlimited capacity
- 7 indexed fields
- Instant local access
🖥️ Backup: Server SQLite
- Via MHA Collector API
- Cross-device sync
- Persistent backup
- Query from anywhere
Benefits
Full traceability
Every message linked to its conversation via correlation IDs
Audit compliance
Complete history with timestamps and optional signatures
Agent interop
Standard format for all agent-to-agent communication
Conversation threading
Reopen any conversation from the activity log
Debugging
Trace issues through correlation chains end-to-end
Analytics
Query patterns by intent, agent, time, or any field
Decision Evidence
AEE envelopes can carry structured decision evidence: a compact record of what information an agent considered, what it decided, and why. This is defined in the requires.decision_evidence contract and stored in payload.decision_evidence.
Evidence levels
| Level | Fields captured | Use case |
|---|---|---|
none | No evidence recorded | Low-risk, high-volume operations |
minimal | decision, action_taken, confidence | Basic audit trail |
standard | All minimal + inputs_used, tools_used, reason_summary | Operational accountability |
full | All standard + context_refs, full reasoning chain | Regulated environments, incident forensics |
{
"v": "1",
"type": "result",
"from": "agent.sentinel",
"intent": "quox.chat.response",
"requires": {
"decision_evidence": "standard"
},
"payload": {
"text": "Restarted nginx on nw-worker-01.",
"decision_evidence": {
"inputs_used": ["alert.severity: critical", "host: nw-worker-01"],
"tools_used": ["fleet_status", "service_health"],
"decision": "restart_service",
"reason_summary": "nginx unresponsive, no maintenance window active",
"action_taken": "systemctl restart nginx",
"confidence": 0.92
}
}
}Evidence records are automatically written to the VOLT ledger as agent.decision.recorded events, creating a tamper-evident chain. External parties can verify the chain via WARD witness receipts without accessing the evidence content.
The Decision Evidence plugin provides a timeline view, search, export, and per-agent configuration in the QuoxCORE dashboard.
Open Specification
AEE is fully specified and implemented in QuoxCORE today. It is a live IETF Internet-Draft (draft-cowles-aee-01), filed 2026-02-28.
AEE specification on GitHub · draft-cowles-aee-01 on the IETF datatracker
From the blog