# MoAI-ADK Agents Integration

How macOS Resource Optimizer integrates with MoAI-ADK agents.

## Agent Architecture

The optimizer uses MoAI-ADK agents for command orchestration:

```
Command Input
    ↓
MoAI Agent Handler
    ├─ manager-optimizer (Orchestration)
    ├─ expert-analyzer (Analysis)
    ├─ expert-optimizer (Optimization)
    └─ expert-monitor (Monitoring)
    ↓
Python Engine
    ↓
Response
```

## Available Agents

### manager-optimizer

**Role**: Command orchestration and routing

**Responsibilities**:
- Parse incoming commands
- Route to appropriate handlers
- Coordinate expert execution
- Generate responses
- Handle errors

**Invoked by**:
- `/macos-resource-optimizer:0-init`
- `/macos-resource-optimizer:1-analyze`
- `/macos-resource-optimizer:2-optimize`
- `/macos-resource-optimizer:3-monitor`
- `/macos-resource-optimizer:4-report`
- `/macos-resource-optimizer:9-feedback`

### expert-analyzer

**Role**: System analysis and metrics collection

**Responsibilities**:
- Collect system metrics
- Analyze current state
- Identify optimization opportunities
- Generate recommendations

**Capabilities**:
- CPU analysis
- Memory analysis
- Disk analysis
- Battery analysis
- Thermal analysis
- Network analysis

### expert-optimizer

**Role**: Optimization planning and execution

**Responsibilities**:
- Plan optimizations
- Apply changes
- Monitor impact
- Handle rollback

**Capabilities**:
- CPU optimization
- Memory optimization
- Disk optimization
- Battery optimization
- Thermal optimization
- Network optimization

### expert-monitor

**Role**: Continuous performance monitoring

**Responsibilities**:
- Real-time metric collection
- Alert generation
- Trend analysis
- Historical tracking

**Capabilities**:
- Continuous monitoring
- Alert generation
- Data export
- Trend analysis

## Agent Communication Flow

```
User Command
    ↓
/macos-resource-optimizer:X
    ↓
Manager parses command
    ↓
Routes to Expert(s)
    ↓
Expert(s) execute task(s) (parallel)
    ↓
Collect results
    ↓
Format response
    ↓
Return to user
```

## Token Budget by Command

| Command | Manager | Expert(s) | Total |
|---------|---------|-----------|-------|
| 0-init | 2K | 3K | 5K |
| 1-analyze | 3K | 12K | 15K |
| 2-optimize | 4K | 16K | 20K |
| 3-monitor | 2K | 8K | 10K |
| 4-report | 3K | 5K | 8K |
| 9-feedback | 1K | 1K | 2K |

## Parallel Execution

Experts run in parallel for speed:

```python
# All experts run simultaneously
results = await asyncio.gather(
    expert_analyzer.analyze_cpu(),
    expert_analyzer.analyze_memory(),
    expert_analyzer.analyze_disk(),
    expert_analyzer.analyze_battery(),
    expert_analyzer.analyze_thermal(),
    expert_analyzer.analyze_network()
)
```

Result: 6× speedup compared to sequential execution

## Error Handling

Agents handle errors gracefully:

```
Expert fails
    ↓
Manager catches error
    ↓
Logs error
    ↓
Continues with other experts
    ↓
Returns partial results
    ↓
User notified of failures
```

## Extending with Custom Agents

You can create custom agents:

```python
class CustomOptimizer(Agent):
    """Custom optimization expert"""

    async def optimize(self, strategy='balanced'):
        # Your optimization logic
        pass
```

Register with manager:

```python
manager.register_expert('custom-optimizer', CustomOptimizer())
```

## Agent Delegation Pattern

Alfred (MoAI orchestrator) delegates to agents:

```python
# Alfred delegates to expert
result = Task(
    subagent_type="expert-optimizer",
    prompt="Optimize system with balanced strategy"
)

# Expert returns results
result.status  # "success"
result.data    # Optimization results
```

## Performance Characteristics

### Agent Execution Times

- **manager-optimizer**: ~100ms (parsing, coordination)
- **expert-analyzer**: ~1.5-1.8s (parallel analysis)
- **expert-optimizer**: ~1.8-2.0s (parallel optimization)
- **expert-monitor**: ~0.5-3.0s (configurable)

### Resource Usage

- **Manager**: ~5MB memory
- **Each Expert**: ~15-20MB memory
- **Total system**: ~50-100MB peak

## Integration Points

### With MoAI-ADK

- Uses standard agent patterns
- Follows MoAI naming conventions
- Implements MoAI interfaces
- Supports MoAI delegation

### With Claude Code

- Responds to Claude Code commands
- Uses Claude Code tools
- Integrates with Claude Code workflow
- Supports Claude Code customization

## Advanced Usage

### Direct Agent Invocation

Advanced users can invoke agents directly:

```python
from macos_optimizer.agents import expert_analyzer

analyzer = expert_analyzer.ExpertAnalyzer()
results = analyzer.analyze(components=['cpu', 'memory'])
```

### Custom Workflows

Create custom workflows:

```python
from macos_optimizer.agents import manager_optimizer

manager = manager_optimizer.ManagerOptimizer()

# Run custom workflow
manager.init()
manager.analyze()
manager.optimize(strategy='custom')
manager.report()
```

### Agent Chaining

Chain agents for complex operations:

```python
# Analyze → Plan → Optimize → Report
analyze_result = expert_analyzer.analyze()
plan_result = expert_optimizer.plan(analyze_result)
optimize_result = expert_optimizer.optimize(plan_result)
report_result = generate_report(optimize_result)
```

## Monitoring Agents

Monitor agent execution:

```bash
# View agent logs
log stream --predicate 'process contains "optimizer"'

# Monitor agent performance
/macos-resource-optimizer:3-monitor --agent-metrics

# Profile agent execution
/macos-resource-optimizer:1-analyze --profile agents
```

## Agent Statistics

View agent performance:

```bash
/macos-resource-optimizer:4-report --type technical --component agents
```

Shows:
- Agent execution times
- Token usage per agent
- Error rates
- Success rates

## Next Steps

- Learn [Commands Reference](/commands/index)
- Explore [Architecture](/architecture/overview)
- Review [API Reference](/api/index)
- See [Advanced Integration](#advanced-usage)

## Support

For agent-related questions:
- Check [Architecture Overview](/architecture/overview)
- Review [API Documentation](/api/index)
- Submit feedback: `/macos-resource-optimizer:9-feedback`

## Related Documentation

- [MoAI-ADK Architecture](/architecture/overview)
- [Integration Flow](/architecture/integration-flow)
- [Commands Reference](/commands/index)
- [API Reference](/api/index)
