docs/multi-agent-architecture.md

# Multi-Agent Architecture for HuggingClaw World

## Overview

The HuggingClaw World multi-agent system enables coordinated operation of multiple specialized agents (Adam, Eve, Cain) with role-based access control (RBAC) and inter-agent communication via A2A protocol.

## Architecture

### Agent Roles

| Agent | Role | Responsibilities |
|-------|------|-------------------|
| **Adam** | Infrastructure | System-level operations, deployment, monitoring, HuggingFace Space management |
| **Eve** | UI Logic | Frontend rendering, display management, user interface |
| **Cain** | Interaction | User message processing, conversation handling, memory management |

### File Structure

```
.openclaw/
├── agents/
│   ├── registry.json          # Agent registry with capabilities and status
│   ├── rbac.py                # Role-based access control implementation
│   └── main/
│       └── sessions/          # Agent session data
├── workspace/
│   ├── state.json             # Workspace state with multi-agent configuration
│   └── MULTI_AGENT.md         # This documentation
├── cron/
│   ├── executor.py            # Cron job executor with tool registry
│   └── jobs.json              # Job configurations
└── openclaw.json              # OpenClaw configuration
```

## State Management

### workspace/state.json

The workspace state file tracks:

- **Multi-agent mode**: Enable/disable multi-agent operation
- **Agent states**: Current status of each agent (active, idle, offline, error)
- **Active agent**: Which agent is currently running
- **Agent communication**: A2A peer endpoints
- **Permissions**: Role-based access control settings

### agents/registry.json

The agent registry tracks:

- **Agent metadata**: Name, role, workspace, description
- **Capabilities**: Allowed and forbidden tools per agent
- **Health status**: Last check time, status, failure count
- **Communication endpoints**: A2A JSON-RPC endpoints

## Role-Based Access Control

### TOOL_REGISTRY

The central `TOOL_REGISTRY` in `rbac.py` defines:

- **Tool metadata**: Description, required authentication level
- **Role mapping**: Which roles can use each tool
- **Permission level**: ALLOWED, FORBIDDEN, or ROLE_SPECIFIC

### Tool Categories

#### Infrastructure Tools (Adam only)
- `hf_space_status` - Check HuggingFace Space status
- `hf_restart_space` - Restart a HuggingFace Space
- `hf_create_space` - Create a new Space
- `hf_delete_space` - Delete a Space
- `deploy_agent` - Deploy a new agent instance
- `system_monitor` - Monitor system health
- `log_viewer` - View system logs

#### UI Tools (Eve only)
- `ui_render` - Render UI components
- `frontend_update` - Update frontend content
- `bubble_set` - Set speech bubble text
- `chatlog_post` - Post chat log entries
- `display_manage` - Manage display settings
- `theme_update` - Update UI theme

#### Interaction Tools (Cain only)
- `message_send` - Send messages via A2A
- `conversation_process` - Process conversation input
- `memory_read` - Read from agent memory
- `memory_write` - Write to agent memory
- `session_archive` - Archive old sessions
- `context_manage` - Manage conversation context

#### Shared Tools (All agents)
- `health_check` - Perform health check
- `get_status` - Get agent status
- `agent_ping` - Ping another agent

## Usage

### Initialize the RBAC System

```python
from .openclaw.agents.rbac import MultiAgentSystem, check_permission, filter_tools_for_agent

# Get the RBAC system instance
rbac = MultiAgentSystem()

# Check if current agent can use a tool
if rbac.check_tool_permission("hf_restart_space"):
    # Execute the tool
    pass

# Get allowed tools for current agent
allowed_tools = rbac.get_allowed_tools()

# Get peer agents for A2A communication
peers = rbac.get_peers()
```

### Permission Checking

```python
# Check permission for a specific agent
from .openclaw.agents.rbac import check_permission

# Check if Cain can use a tool
can_use = check_permission("message_send", "cain")

# Check if Adam can use a tool
can_restart = check_permission("hf_restart_space", "adam")
```

### Filter Tools for Agent

```python
from .openclaw.agents.rbac import filter_tools_for_agent

all_tools = ["hf_restart_space", "ui_render", "message_send"]

# Filter for Cain
cain_tools = filter_tools_for_agent(all_tools, "cain")
# Returns: ["message_send"]

# Filter for Eve
eve_tools = filter_tools_for_agent(all_tools, "eve")
# Returns: ["ui_render"]
```

## A2A Communication

Agents communicate via A2A (Agent-to-Agent) JSON-RPC protocol:

```python
import requests

def send_a2a_message(agent_url, message):
    """Send message to another agent via A2A"""
    payload = {
        "jsonrpc": "2.0",
        "id": f"msg-{int(time.time())}",
        "method": "message/send",
        "params": {
            "message": {
                "messageId": f"msg-{int(time.time())}",
                "role": "user",
                "parts": [{"type": "text", "text": message}]
            }
        }
    }
    response = requests.post(f"{agent_url}/a2a/jsonrpc", json=payload, timeout=90)
    return response.json()
```

## Backward Compatibility

The system maintains full backward compatibility with single-agent workflows:

### Legacy Mode

```python
# Enable legacy mode for single-agent operation
rbac = MultiAgentSystem(legacy_mode=True)

# In legacy mode, all tools are available
allowed_tools = rbac.get_allowed_tools()  # Returns all tools
```

### Convenience Functions

```python
from .openclaw.agents.rbac import can_use_tool, get_available_tools

# Single-agent compatible API
if can_use_tool("some_tool"):
    # Execute tool
    pass

# Get all available tools for current agent
tools = get_available_tools()
```

## Configuration

### Environment Variables

- `AGENT_NAME` - Name of the current agent (adam, eve, cain)
- `SPACE_ID` - HuggingFace Space ID (used for auto-detection)
- `A2A_PEERS` - Comma-separated list of peer agent URLs

### Multi-Agent Enable/Disable

Set in `workspace/state.json`:

```json
{
  "multi_agent_enabled": true,
  "legacy_mode": false
}
```

## Agent Detection

The system auto-detects the current agent based on:

1. `AGENT_NAME` environment variable
2. `SPACE_ID` environment variable
3. Defaults to "cain" if not found

## Health Monitoring

Agent health is tracked in the registry:

```json
{
  "health": {
    "last_check": "2026-03-14T00:00:00Z",
    "status": "healthy",
    "failures": 0
  }
}
```

Status values: `healthy`, `degraded`, `error`, `unknown`

## Error Handling

- Permission denied: Tool execution is blocked with log message
- Unknown tool: Warning logged, execution blocked
- Agent not found: Returns empty info dict
- Invalid role: Defaults to INTERACTION role

## Security

- Infrastructure tools require authentication
- Dangerous tools (restart, delete) marked in registry
- Role-based isolation prevents cross-role tool access
- A2A communication uses token-based auth

## Future Extensions

Potential additions:

- Dynamic tool registration
- Agent capability discovery
- Load balancing across agents
- Agent migration and failover
- Resource quota management
- Audit logging

## Migration Guide

To migrate from single-agent to multi-agent:

1. Create `workspace/state.json` with multi-agent configuration
2. Create `agents/registry.json` with agent definitions
3. Update code to use `rbac.py` for permission checks
4. Add A2A communication for inter-agent messages
5. Test in legacy mode first, then enable multi-agent

## Troubleshooting

### Agent not detected

Check environment variables:
```bash
echo $AGENT_NAME
echo $SPACE_ID
```

### Permission denied

Verify tool is in agent's allowed list in `registry.json`

### A2A communication fails

Check peer endpoints are reachable:
```bash
curl https://peer-agent.hf.space/a2a/jsonrpc
```

### Multi-agent mode not working

Verify `multi_agent_enabled: true` in `workspace/state.json`