Skip to main content

ADR-003: Agent Orchestration Mapping

Status​

Proposed

Context​

CODITECT has evolved multiple agent orchestration patterns across 776 agents:

CODITECT Patterns (Implicit):

  • MoE (Mixture of Experts): Router selects single best agent from candidate pool
  • Independent Parallel: Multiple agents execute different tasks without coordination
  • Orchestrator-Delegated: Central coordinator dispatches work to specialized agents
  • Peer Review: Multiple agents analyze same input, results compared/voted
  • Sequential Pipeline: Output of one agent becomes input to next

Brainqub3 Agent Labs provides 5 explicit architecture types based on arXiv:2512.08296:

Agent Labs Architectures (Explicit):

  1. SAS (Single-Agent System): One agent handles the entire task
  2. Independent: Multiple agents work in parallel without communication
  3. Centralised: Central coordinator delegates to specialized agents
  4. Decentralised: Peer-to-peer agent communication with consensus
  5. Hybrid: Combination of centralised coordination + peer communication

To benchmark CODITECT orchestration using Agent Labs, we must define a mapping between these pattern sets. The mapping determines which CODITECT behaviors can be analyzed with which Agent Labs metrics.

Key constraints:

  • Not all CODITECT patterns have exact Agent Labs equivalents
  • Some CODITECT behaviors span multiple Agent Labs types
  • The mapping must preserve semantic intent (e.g., "no coordination" vs "full consensus")
  • Agent Labs coordination metrics (overhead, message density, redundancy) depend on architecture type

Decision​

Establish the following mapping from CODITECT orchestration patterns to Agent Labs architecture types:

CODITECT PatternAgent Labs TypeJustification
MoE (single selection)SASRouter selects one agent; effectively single-agent from task perspective
Independent ParallelIndependentDirect match: no coordination, parallel execution
Orchestrator-DelegatedCentralised or HybridCentralised if no peer communication; Hybrid if agents can exchange info
Peer ReviewDecentralisedAgents independently analyze, then consensus/voting (peer communication)
Sequential PipelineCentralisedOrchestrator manages handoffs; agents don't directly communicate

Adapter Implementation: Create scripts/scaling-analysis/adapter.py to translate CODITECT agent invocations into Agent Labs experiment configurations. The adapter will:

  1. Detect orchestration pattern from CODITECT command metadata or invocation structure
  2. Map to Agent Labs architecture using the table above
  3. Configure experiment parameters (agent count, communication topology, task distribution)
  4. Execute Agent Labs run with CODITECT agents as experimental subjects
  5. Report coordination metrics back to CODITECT for analysis

Ambiguity Resolution:

  • Orchestrator-Delegated → Centralised vs Hybrid: Default to Centralised unless CODITECT agents explicitly share state (then Hybrid)
  • MoE (multi-selection) → Independent: If MoE invokes multiple agents in parallel with no coordination, map to Independent
  • Undefined patterns → Manual classification: Log warning and require explicit --architecture flag

Alternatives Considered​

1. One-to-One Strict Mapping​

Pros:

  • Simplest implementation
  • Clear, unambiguous

Cons:

  • CODITECT has more patterns than Agent Labs types (5 CODITECT → 5 Agent Labs forces lossy mapping)
  • Ignores nuance (e.g., Orchestrator-Delegated can be Centralised OR Hybrid)
  • Fails when new CODITECT patterns emerge

2. Extended Agent Labs Types​

Pros:

  • Could define CODITECT-specific architecture types (e.g., "MoE-Orchestrated")
  • Preserves all nuance

Cons:

  • Breaks compatibility with paper-aligned model (arXiv:2512.08296 only defines 5 types)
  • Cannot use Agent Labs built-in coordination metrics
  • Loses ability to compare CODITECT results with Agent Labs baseline experiments
  • High maintenance burden (must extend scaling model math)

3. Multi-Architecture Experiments (Run Same Task with Multiple Mappings)​

Pros:

  • Explores parameter space fully
  • Captures ambiguity in data

Cons:

  • Expensive (5x API cost per experiment)
  • Adds complexity without clear benefit
  • Results difficult to interpret (which architecture is "true"?)

4. No Mapping (Manual Configuration Only)​

Pros:

  • Maximum flexibility
  • User controls everything

Cons:

  • High friction for experimentation
  • Requires deep understanding of both CODITECT and Agent Labs
  • Error-prone (easy to misclassify)
  • No automation benefits

Consequences​

Positive​

  1. Benchmarking Enabled: CODITECT orchestration patterns can now be quantitatively analyzed
  2. Coordination Metrics: Access to 5 metrics (overhead, message density, redundancy, efficiency, error amplification)
  3. Pattern Validation: Can test whether CODITECT patterns match theoretical scaling predictions
  4. Cost Optimization: Identify which patterns have high coordination overhead for specific task types
  5. Standardized Vocabulary: Agent Labs types provide common language for discussing orchestration
  6. Automatic Classification: Adapter reduces manual experiment setup
  7. Incremental Adoption: Can start with clear mappings (Independent, Centralised), add nuance later

Negative​

  1. Lossy Mapping: Some CODITECT nuance lost in translation (e.g., MoE router intelligence not captured)
  2. Adapter Complexity: Must maintain mapping logic as CODITECT patterns evolve
  3. Ambiguity: Orchestrator-Delegated requires runtime detection of peer communication
  4. False Equivalence Risk: Agent Labs "Centralised" assumes specific coordination topology that might not match CODITECT
  5. Limited Pattern Coverage: New CODITECT patterns (e.g., Hierarchical Orchestration) have no clear mapping
  6. Measurement Bias: Coordination metrics designed for Agent Labs types might not fully capture CODITECT behavior

Risks​

  1. Misclassification: Adapter incorrectly maps CODITECT pattern, leading to invalid metrics

    • Mitigation: Log classification decisions; allow manual override with --architecture flag

  2. Pattern Drift: CODITECT orchestration evolves, mapping becomes stale

    • Mitigation: Version adapter alongside CODITECT releases; include pattern detection tests

  3. Metric Misinterpretation: Users treat coordination metrics as absolute when they're architecture-specific

    • Mitigation: Document metric semantics; include architecture type in all reports

  4. Over-Simplification: Mapping forces binary choices (Centralised vs Hybrid) when reality is spectrum

    • Mitigation: Support "closest match" heuristic; expose uncertainty in logs

  5. Incompleteness: Not all CODITECT use cases fit Agent Labs types

    • Mitigation: Identify gaps early; extend mapping incrementally; document known limitations

Implementation Notes​

Adapter Module Structure​

# scripts/scaling-analysis/adapter.py

from enum import Enum
from typing import Optional

class AgentLabsArchitecture(Enum):
    SAS = "sas"
    INDEPENDENT = "independent"
    CENTRALISED = "centralised"
    DECENTRALISED = "decentralised"
    HYBRID = "hybrid"

class CODITECTPattern(Enum):
    MOE_SINGLE = "moe_single"
    INDEPENDENT_PARALLEL = "independent_parallel"
    ORCHESTRATOR_DELEGATED = "orchestrator_delegated"
    PEER_REVIEW = "peer_review"
    SEQUENTIAL_PIPELINE = "sequential_pipeline"

PATTERN_MAPPING = {
    CODITECTPattern.MOE_SINGLE: AgentLabsArchitecture.SAS,
    CODITECTPattern.INDEPENDENT_PARALLEL: AgentLabsArchitecture.INDEPENDENT,
    CODITECTPattern.PEER_REVIEW: AgentLabsArchitecture.DECENTRALISED,
    CODITECTPattern.SEQUENTIAL_PIPELINE: AgentLabsArchitecture.CENTRALISED,
    # ORCHESTRATOR_DELEGATED handled dynamically
}

def detect_pattern(command_metadata: dict) -> CODITECTPattern:
    """Detect CODITECT orchestration pattern from command/task metadata."""
    # Implementation: analyze command structure, agent invocation count, etc.
    pass

def map_to_architecture(
    pattern: CODITECTPattern,
    has_peer_communication: bool = False
) -> AgentLabsArchitecture:
    """Map CODITECT pattern to Agent Labs architecture type."""
    if pattern == CODITECTPattern.ORCHESTRATOR_DELEGATED:
        return (AgentLabsArchitecture.HYBRID if has_peer_communication
                else AgentLabsArchitecture.CENTRALISED)
    return PATTERN_MAPPING.get(pattern, AgentLabsArchitecture.SAS)

Example Mapping Flow​

# User invokes CODITECT command
/agent-compare frontend-react-expert backend-api-expert security-specialist "analyze auth flow"

# Adapter detects pattern
pattern = detect_pattern({
    "agent_count": 3,
    "coordination": "orchestrator",  # From command metadata
    "peer_communication": False
})
# Result: CODITECTPattern.ORCHESTRATOR_DELEGATED

# Map to Agent Labs type
architecture = map_to_architecture(pattern, has_peer_communication=False)
# Result: AgentLabsArchitecture.CENTRALISED

# Configure Agent Labs experiment
agent-labs run \
  --scenario coditect_auth_flow_analysis \
  --architecture centralised \
  --agents 3 \
  --coordinator-type orchestrator

Pattern Detection Heuristics​

IndicatorPattern
Single agent invokedMOE_SINGLE or SAS
Multiple agents, no coordination flagINDEPENDENT_PARALLEL
Orchestrator role presentORCHESTRATOR_DELEGATED
"review", "vote", "consensus" in metadataPEER_REVIEW
Agent outputs chained (A→B→C)SEQUENTIAL_PIPELINE

Manual Override​

# Adapter auto-detects Centralised, but user knows it's Hybrid
/scaling-run coditect_task --architecture hybrid --override-detection

Logging Example​

[scaling-adapter] Detected pattern: ORCHESTRATOR_DELEGATED
[scaling-adapter] Peer communication: False
[scaling-adapter] Mapped to Agent Labs architecture: CENTRALISED
[scaling-adapter] Running experiment with 4 agents...

Future Extensions​

  1. Dynamic Topology Detection: Analyze actual message passing at runtime to refine Centralised vs Hybrid classification
  2. Pattern Taxonomy Expansion: Add new CODITECT patterns as they emerge (e.g., Hierarchical, Streaming)
  3. Confidence Scores: Report mapping confidence (e.g., "80% Centralised, 20% Hybrid")
  4. Agent Labs Type Extensions: Propose new architecture types to Agent Labs upstream if CODITECT uncovers novel patterns

References​

  • Paper: arXiv:2512.08296 - "Scaling Laws for Multi-Agent Systems"
  • Agent Labs Architectures: Section 2.2 "Architecture Types"
  • CODITECT MoE Patterns: skills/moe-task-execution/SKILL.md
  • CODITECT Agent System: agents/ directory (776 agents)
  • Related ADRs:
    • ADR-001: Agent Labs Adoption
    • ADR-002: Integration Pattern
    • ADR-004: Scaling Model for Agent Selection

Author: Claude (Sonnet 4.5) Date: 2026-02-16 Track: H (Framework) Task ID: H.0