Building Blocks

Every VOX system is composed of core abstractions. This page provides a high-level overview — each building block has its own dedicated article with full details.

┌─────────────────────────────────────────────────┐
│                  VOXOrchestrator                │
│  Agent discovery · Capability registry          │
│  Lifecycle management · Message routing         │
│                                                 │
│   ┌──────────┐   ┌──────────┐   ┌──────────┐   │
│   │ VOXAgent │   │ VOXAgent │   │ VOXAgent │   │
│   │  (root)  │   │ (child)  │   │ (child)  │   │
│   └────┬─────┘   └──────────┘   └──────────┘   │
│        │                                        │
│  ┌─────▼─────────────────────────────────────┐  │
│  │ VOXAgent internals                        │  │
│  │                                           │  │
│  │  ┌──────────┐  ┌──────────────────────┐   │  │
│  │  │ VOXRole  │  │ VOXBoundCapability   │   │  │
│  │  │  (chat)  │──│  ai.llm              │   │  │
│  │  │          │  │                      │   │  │
│  │  │ (other..)│──│  comm.gateway        │   │  │
│  │  │          │  │                      │   │  │
│  │  │          │──│  net.browser         │   │  │
│  │  └──────────┘  └──────────────────────┘   │  │
│  │                                           │  │
│  │  VOXMessage  ◄─── inter-agent bus         │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

---

VOXOrchestrator

The runtime kernel. Owns all agent and capability state, manages discovery and lifecycle, and routes inbound messages / VOXMessage envelopes.

"The orchestrator is the single source of truth for the fleet." → vox/orchestration/base.py

---

VOXAgent

A self-contained execution unit with a unique identity (UUID), mounted capabilities, and loaded roles. Agents declare configuration in agent.yml, host behavioral roles in roles/*.py, and communicate via events and messages.

"The 'I' in the VOX system." → vox/agents/base.py

---

VOXCapability

The atomic unit of system permission. Wraps an external service behind a clean async interface. Split into a stateless singleton (VOXCapability) and a per-agent proxy (VOXBoundCapability) with resolved configuration, stored on the agent as self.capabilities[cap_id].

"Agents hold no implicit system power." → vox/capabilities/base.py

---

VOXRole

A modular behavioral unit attached to an agent. Handles events (self.on()) and exposes commands (@command()). Every role declares its required capabilities via REQUIRES, discovered statically at boot.

"Role = what the agent can do and what it reacts to." → vox/roles/base.py

---

VOXMessage

The inter-agent envelope — a frozen pydantic model (message_id, source, target, type, details, reply_to) conforming to the VOX Messaging Contract. Drives the delegation protocol.

"All inter-agent communication flows through VOXMessage." → vox/messaging/models.py

---

VOXApiServer

The HTTP interface over the VOX runtime. Serves port 8000 with endpoints for fleet snapshots, agent lifecycle commands, capability monitoring, and command introspection. Bearer-token protected when VOX_API_TOKEN is set.

"Manage the fleet without touching Python." → vox/api_server.py

---

Runtime Scenario

Agent declares in agent.yml:
  name, id, master_id, autostart, conversational, roles: [...]

Roles load from agent_dir/roles/*.py:
  chat.py, and any other role modules

Orchestrator:
  └── mounts capabilities required by roles' REQUIRES
        → agent.capabilities["ai.llm"], agent.capabilities["comm.gateway"]
  └── loads roles → registers on_boot, inbound_message, send_message

Inbound message arrives (webhook):
  → comm.gateway adapter verifies + parses
  → orchestrator.dispatch_inbound_message(source="comm.gateway", payload=...)
  → agent.emit("inbound_message", source=..., ...)
    → chat role classifies intent against the command registry
    → dispatch to own command or delegated child

Outbound reply:
  → agent.capabilities["comm.gateway"].send_text("telegram", user_id, text)

---

Overview of Related Pages

Page	What it covers
Capability Contract	Writing a new capability — checklist, template, lifecycle
Comm Gateway	Multi-channel messaging and adapter contract
Capabilities Reference	Current capability inventory
Messaging Contract	Full message envelope spec, event payloads, logging contract
Security Architecture	Permission model, OCAP principles, speaker verification