VOXMessage

File: vox/messaging/models.py

The inter-agent envelope. All messages between agents follow this structure, conforming to the Messaging Contract v1.0. VOXMessage is a frozen pydantic.BaseModel (immutable) with UUID-typed identity fields.

class VOXMessage(BaseModel):
    message_id: UUID                 # globally unique UUID
    message_source: str              # source of truth (e.g. interface name)
    emitted_at: str                  # ISO-8601 datetime with timezone
    source: UUID                     # UUID of the sender agent
    target: UUID                     # UUID of the recipient agent
    type: str                        # semantic intent
    details: dict                    # event-specific variable payload
    reply_to: UUID | None            # UUID of the message this replies to

Model config: frozen=True (immutability), populate_by_name=True.

Message Types

The message type constants live in vox.messaging:

Constant	Value	Direction	Purpose
MSG_COMMAND_REQUEST	"command_request"	Parent → Child	Request execution of a named command
MSG_ACKNOWLEDGED	"message_acknowledged"	Any → Any	Confirm receipt (auto-sent)
MSG_COMMAND_RESULT	"command_result"	Child → Parent	Deliver execution result
MSG_COMMAND_ERROR	"command_error"	Any → Any	Report delivery or execution failure

Import

from vox.messaging import (
    VOXMessage,
    MSG_COMMAND_REQUEST,    # "command_request"
    MSG_ACKNOWLEDGED,       # "message_acknowledged"
    MSG_COMMAND_RESULT,     # "command_result"
    MSG_COMMAND_ERROR,      # "command_error"
)

Where messages flow

Messages are routed through the orchestrator:

• Inbound (webhooks, capabilities): orchestrator.dispatch_inbound_message( source=..., payload=...), wrapped to catch SecurityError (guardrail). The orchestrator sanitizes the payload and fans it out to the relevant agent via agent.emit("inbound_message", source=..., **payload).
• Events within an agent: agent.emit(event_name, **kwargs) dispatches to role handlers (self.on(event_name)).
• Delegation between agents follows the Hierarchical Messaging Contract.

The full message envelope specification, including event-specific payloads and logging contract, is documented in the Messaging Contract.