Multi-Agent Integration (v3.0)

Overview

Agent Architecture

                    UnifiedOrchestrator (Opus)
                   (Synthesizes all recommendations)
                              |
        +---------------------+---------------------+
        |                     |                     |
   Training (5)          Trading (5)          Selection (4)
   - Hyperparameter      - Signal Analyst     - Symbol Scorer
   - Risk Analyst        - Risk Guardian      - Weight Optimizer
   - Reward Engineer     - Position Sizer     - Compatibility Auditor
   - Data Monitor        - Execution Timer    - Portfolio Coherence
   - Backtest Validator  - Exit Strategist
                              |
                    SharedAgentContext
                   (Thread-safe singleton)
                              |
                    AgentSafetyWrapper
                   (Bounds, rate limits, veto)

Agent Roles by System

Training Agents (5)

Live Trading Agents (5)

Selection Agents (4)

Safety Mechanisms

Forbidden Actions (Agents can NEVER take)

• bypassallgates
• disableriskcontrols
• unlimited_position
• ignore_drawdown
• forcemargincall
• delete_models
• modifyapikeys

Safety Bounds (All values clamped)

Training Phase Gates (v3.0 - "Primum Non Nocere")

v2.4 Experiment Result: Agents HURT performance (fitness -38.2%, PF -6.3%). Primary cause: compounding entropy increases at 63% progress. v3.0 guardrails prevent this.

Rate Limiting

Veto Authority

• Risk Guardian has veto power for safety-critical decisions
• Veto reasoning logged and auditable
• Orchestrator can override only with strong evidence

Operating Modes

Integration: Training

Configuration

from alpaca_trading.training import MultiAgentTrainer, MultiAgentConfig

agent_config = MultiAgentConfig(
    # Enable/disable agents
    enable_hyperparameter_tuner=True,
    enable_risk_analyst=True,
    enable_reward_engineer=True,  # READ-ONLY diagnostic in v3.0
    enable_data_monitor=False,
    enable_backtest_validator=False,

    # Consultation intervals (v3.0: reduced from 5/3/10)
    hyperparam_interval=8,
    risk_interval=5,
    reward_interval=15,

    # v3.0: Phase gates
    no_intervention_before_pct=30.0,        # Skip consultations before 30%
    entropy_decrease_only_after_pct=50.0,   # No entropy increases after 50%

    # v3.0: Cumulative entropy bounds
    max_cumulative_entropy_multiplier=1.5,  # Never exceed 1.5x initial
    min_cumulative_entropy_multiplier=0.5,  # Never below 0.5x initial

    # v3.0: Agent memory
    memory_dir='data/agent_memory',
    symbol='AAPL',  # Set per training run

    # Cost control
    max_consultations_per_run=50,
    log_agent_responses=True,
)

Usage

# Create multi-agent trainer
trainer = MultiAgentTrainer(env, ppo_config, agent_config)

# Train with agent guidance
import asyncio
results = asyncio.run(trainer.train_with_guidance())

# Save agent logs
trainer.save_agent_logs("agent_logs.json")

Integration: Live Trading

Configuration

from alpaca_trading.agents import (
    UnifiedOrchestrator,
    OrchestratorConfig,
    OrchestratorMode,
)

orchestrator = UnifiedOrchestrator(
    config=OrchestratorConfig(
        mode=OrchestratorMode.ADVISORY,  # Start safe
        enable_trading_agents=True,
        enable_selection_agents=False,
        min_consensus_for_action=0.66,  # 2/3 agreement
        require_unanimous_for_critical=True,
        max_total_consultations_per_hour=200,
    )
)

Signal Evaluation

# Consult Signal Analyst
analysis = await trading_agents.evaluate_signal(
    symbol="AAPL",
    direction=1,
    confidence=0.72,
    magnitude=0.015,
    regime="bull",
)

adjusted_confidence = analysis['adjusted_confidence']
recommendation = analysis['recommendation']  # PROCEED, REDUCE_SIZE, SKIP

Gate Check with Risk Guardian

# Risk Guardian has veto authority
risk_assessment = await trading_agents.evaluate_gates(
    symbol=symbol,
    gate_results=gate_results,
    win_rate=0.62,
    loss_streak=1,
    drawdown=0.032,
    exposure=0.45,
)

if risk_assessment['veto']:
    logger.warning(f"Risk Guardian veto: {risk_assessment['veto_reason']}")
    return False

Position Sizing

# Consult Position Sizer
sizing = await trading_agents.recommend_position_scale(
    signal_strength=0.75,
    confidence=0.72,
    volatility=0.24,
    drawdown=0.032,
    exposure=0.45,
    win_rate=0.62,
)

scale = sizing['scale_multiplier']  # 0.3 - 2.0
final_qty = base_qty * scale

Shared Context

from alpaca_trading.agents import get_shared_context

context = get_shared_context()

# Update portfolio state
context.update_portfolio_state(
    total_equity=105000,
    cash_available=45000,
    daily_pnl=320,
    current_drawdown=0.032,
    win_rate=0.625,
)

# Update market state
context.update_market_regime("bull", volatility=0.24)
context.update_trading_session("crypto_only")

Cost Estimates

Annual estimate: ~$350-$700 (100 training runs)

Requirements

• ANTHROPICAPIKEY environment variable
• anthropic package (pip install anthropic)
• Optional: nest_asyncio for Colab compatibility

Files Location

Rollout Strategy

Recommendation: Start with advisory mode for 2-4 weeks to validate agent quality before autonomous mode.

Failed Attempts (Critical)

Key Principles

1. Advisory by Default - Start safe, validate before autonomous
2. Wrapper Pattern - Don't modify core training/trading code
3. Consensus Required - 2/3 agreement for action, unanimous for critical
4. Veto Authority - Risk agents can block unsafe actions
5. Bounds Enforcement - All numeric values clamped to safe ranges
6. Rate Limiting - Prevent API cost explosion
7. Full Audit Trail - Every decision logged with reasoning

References

• docs/reference/AIAGENTREFERENCE.md - Comprehensive guide
• examples/multiagenttraining_example.py - Working example
• Branch: feature/v3.0-multi-agent