05 universal agent interchangeability

Chapter 05: Universal Agent Interchangeability

This chapter specifies AegisBrain's tool-agnostic protocol, enabling arbitrary combinations of AI coding tools to collaborate seamlessly via the standardized UniversalAgentEnvelope.

---

1. Tool-Agnostic Design Rationale

The AI developer ecosystem is highly fragmented:

• Anthropic Claude Code: High cognitive synthesis and reasoning.
• OpenAI Codex CLI: Fast code edits and script execution.
• Google Antigravity CLI: Complex multi-turn workflows and agent coordination.
• Nous Research Hermes: Fast local and cloud-based reasoning agents.
• OpenCode CLI: Flexible terminal-native coding agent supporting diverse cloud models.

Historically, each tool operates in an isolated silo with proprietary prompt formats and incompatible session logs. AegisBrain abstracts these tools into interchangeable components of a single unified pipeline:

               ┌────────────────────────────────────────────────────────┐
               │              CONFIGURABLE TIER 1 BOSS                  │
               │   OpenCode (GPT-6 Astra) | Claude Code | Antigravity   │
               └───────────────────────────┬────────────────────────────┘
                                           │ Dispatches Universal Envelope
                                           ▼
               ┌────────────────────────────────────────────────────────┐
               │              CONFIGURABLE TIER 3 WORKER                │
               │   Codex CLI | Hermes Agent | Local Ollama MoE | Aider  │
               └────────────────────────────────────────────────────────┘

---

2. Supported Boss-Worker Pairings

Any supported tool can be designated as the high-cognition Tier 1 Boss or the fast Tier 3 Execution Worker:

Boss Engine	Worker Engine	Invocation Example
OpenCode	Codex	aegis dispatch "Build API gateway" --boss opencode --worker codex
Codex	OpenCode Free	aegis dispatch "Add user migrations" --boss codex --worker opencode --worker-model deepseek-v4.1-flash-free
Antigravity	Hermes	aegis dispatch "Refactor auth middleware" --boss antigravity --worker hermes
Claude Code	Ollama MoE	aegis dispatch "Implement unit tests" --boss claude --worker ollama --worker-model qwen2.5-coder:7b

---

3. The UniversalAgentEnvelope Schema

Regardless of which tool initiates or executes a task, all communication is normalized through the UniversalAgentEnvelope dataclass defined in aegis.agent_adapters:

@dataclass
class UniversalAgentEnvelope:
    task: str
    boss_name: str
    boss_model: Optional[str] = None
    worker_name: str = "hermes"
    worker_model: Optional[str] = None
    execution_response: AgentExecutionResponse = field(
        default_factory=lambda: AgentExecutionResponse(worker_name="unknown")
    )
    quality_gate_passed: bool = True
    gate_scores: Dict[str, bool] = field(
        default_factory=lambda: {
            "karpathy_simplicity": True,
            "unslop_turnitout": True,
            "security_redteam": True,
            "dual_env_verification": True,
        }
    )
    executive_deliverable: str = ""
    tokens_saved: int = 0
    status: str = "completed"
    metadata: Dict[str, Any] = field(default_factory=dict)

3.1 Field Definitions

• task: The natural-language or structured objective assigned to the pipeline.
• boss_name: Identifier of the Tier 1 supervisory engine (antigravity, opencode, claude, codex).
• boss_model: The specific model checkpoint used by Tier 1 (e.g., gemini-3.8-flash, gpt-6-astra).
• worker_name: Identifier of the Tier 3 muscle tool (hermes, opencode, codex, ollama).
• worker_model: Specific checkpoint executing raw synthesis (e.g., qwen2.5-coder:7b, deepseek-v4.1-flash-free).
• gate_scores: Boolean scorecard for each of the 4 Quality Architecture Gates.
• executive_deliverable: Final signed and verified code output or implementation plan.
• tokens_saved: Calculated token volume offloaded from frontier models to free/local workers.

---

4. Configuration & Dispatch CLI

4.1 Setting the Default Boss

Developers can configure their workstation's default Tier 1 Boss:

# Set default Boss to OpenCode with GPT-6 Astra
aegis hierarchy set-boss opencode --model gpt-6-astra

# Inspect currently active Boss configuration
aegis hierarchy get-boss

4.2 Executing Universal Task Dispatch

Dispatch tasks across arbitrary pairings:

# Execute real dispatch
aegis dispatch "Implement JWT token validation" --boss opencode --worker hermes

# Dry-run simulation returning structured JSON envelope
aegis dispatch "Audit database connection pooling" --boss claude --worker codex --simulate --json