VOX Documentation

Documentation version: v0.5.4

This wiki documents the VOX v0.5.4 release. Documentation changes for unreleased features belong to the development branch/docs and are not considered part of this release documentation.

VOX is a secure, event-driven multi-agent orchestration framework designed for high-integrity automation. This wiki is the central reference for the architectural decisions, security protocols, and integration guidelines.

See Versioning for how the wiki relates to VOX releases.

---

The Agent Model

• VOXAgent — agent declaration (agent.yml), bootstrap flow, key members
• Agent Lifecycle — the nine-state agent state machine
• VOXRole — roles, @command() handlers, and event registration
• Creating an Agent — directory layout and manifest reference

Capabilities

• VOXCapability — the capability abstraction: definition vs binding
• Capabilities Reference — current capability inventory
• Capability Contract — writing a new capability
• Comm Gateway — multi-channel messaging (comm.gateway) and its adapters
• WhatsApp Setup — wiring the WhatsApp Cloud API channel

Messaging

• VOXMessage — the inter-agent envelope
• Messaging Contract — envelope spec and payloads
• Hierarchical Messaging Contract — parent/child delegation
• War Room — emergency escalation protocol

Orchestrator & Control Plane

• VOXOrchestrator — the runtime kernel
• Orchestrator & Control Plane — lifecycle, UDS, fleet operations
• VOXApiServer — the HTTP management interface

Architecture & Design

• Architecture Overview — design philosophy
• Building Blocks — the six core abstractions
• Core Ontology (legacy) — component ontology and structural constraints
• Capability Specification (legacy) — pre-refactor packaging spec
• Segmented Persistence & Forensic Traceability — memory vs store

Security & Governance

• Security Architecture — framework-aligned security controls (OCAP, vault, guardrails, speaker verification)

---

Repository Layout (as documented in v0.5.4)

src/vox/               the Python package
  agents/              VOXAgent, lifecycle, loader, memory, store
  capabilities/        capability registry: ai.llm, comm.email, comm.gateway,
                       comm.voicetotext, net.browser
  messaging/           VOXMessage envelope and message type constants
  orchestration/       VOXOrchestrator, registry, graph, war room, watcher
  roles/               VOXRole contract
  security/            guardrails, rate limiter, vault, speaker profile
  api_server.py        VOXAPIServer (HTTP interface)
  cli.py               vox CLI entry point
agents/                runtime agent definitions (agent.yml + roles/)
tests/                 pytest suite