Creating an Agent

Identity

1. Inside agents/, create a folder (e.g. agents/<agent_name>/). This folder contains the agent's manifest, roles, and state.

2. Create agent.yml:

name: "<agent_name>"
id: "<agent_uuid>"              # required, unique
master_id: ""                   # optional; empty = root agent
autostart: true                 # start on orchestrator boot
conversational: true            # allow free-form LLM conversation
roles: ["chat"]                 # optional; explicit role allow-list
personality:
  rules: |
    You are a helpful assistant.
  messages:
    on_boot: "Ready."

Field	Description
name	Required display name (str).
id	Required UUIDv4 identifier.
master_id	Optional parent's UUIDv4 — establishes hierarchy. Empty = root.
autostart	Optional bool; start on orchestrator boot (default false).
conversational	Optional bool; allow free-form LLM conversation.
roles	Optional role allow-list (names must match files in roles/).
personality	Optional dict consumed by roles (rules, messages).
rate_limit_max_calls / rate_limit_window	Optional rate-limit tuning.

Unknown fields produce manifest warnings; wrong types are rejected at boot.

Roles

Capabilities are not declared in agent.yml. Roles declare their required capability IDs via REQUIRES, and the framework mounts them automatically.

3. Inside the agent folder, create the following subdirectories:

   • roles/ — the agent's behavioral roles (.py files). At least one role must be present or the agent is flagged DEGRADED.
   • assets/ — (Optional) sandboxed persistent assets.
   • memory/ — (Optional) agent-private memory: append-only forensic ledger (logs.db) and operational store (memory.db).

Example role

# agents/<agent_name>/roles/chat.py
from vox.roles import VOXRole


class ChatRole(VOXRole):
    REQUIRES = {"ai.llm", "comm.gateway"}

    def __init__(self, agent):
        super().__init__(agent)
        self.on("on_boot")(self._greet)
        self.on("inbound_message")(self._receive_message)

    async def _greet(self, **kwargs):
        text = self.agent.config.get("personality", {}).get("messages", {}).get("on_boot", "Ready.")
        await self.agent.capabilities["comm.gateway"].send_text(
            "telegram", recipient_id, text  # channel, recipient, text
        )

    async def _receive_message(self, source: str = "", text: str = "", **kwargs):
        ...

Identity and secrets

• Each agent may have a secrets.vault (encrypted) managed via tools/provision_vault.py; sensitive capability params are injected from it.
• Agents use the per-agent .env file for non-secret overrides and VOX_MASTER_KEY in the environment to unlock the vault.