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

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

# 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

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:

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

# 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

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:

{
  "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:

{
  "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:

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:

curl https://peer-agent.hf.space/a2a/jsonrpc

Multi-agent mode not working

Verify multi_agent_enabled: true in workspace/state.json