hermes-agent/docs/matrix-bridge.md

Multi-Agent Conversation Bridge

Allows multiple Hermes instances (Timmy, Allegro, Ezra) to communicate with each other through a shared Matrix room.

Overview

The Matrix Bridge enables agent-to-agent coordination without manual intervention. Agents can:

• Send tasks to specific agents
• Broadcast to all agents
• Respond to requests from other agents
• Coordinate on complex workflows

Configuration

Environment Variables

# Enable/disable the bridge
MATRIX_BRIDGE_ENABLED=true

# Shared Matrix room ID for agent communication
MATRIX_BRIDGE_ROOM=!roomid:matrix.example.org

# Agent name (for message routing)
HERMES_AGENT_NAME=Timmy

# Matrix credentials (from existing Matrix gateway config)
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=syt_...

Matrix Room Setup

1. Create a Matrix room for agent communication
2. Invite all agent accounts to the room
3. Set MATRIX_BRIDGE_ROOM to the room ID

Message Format

Messages use a simple prefix format for routing:

[@Allegro] Check the deployment status on VPS
[@Ezra] Can you review PR #456?
[@*] System maintenance in 5 minutes

• [@AgentName] — Message for specific agent
• [@*] — Broadcast to all agents

Usage

Basic Usage

from agent.matrix_bridge import MatrixBridge, send_to_agent, broadcast_to_agents

# Create bridge
bridge = MatrixBridge(agent_name="Timmy")
await bridge.connect()

# Send to specific agent
await bridge.send_to_agent("Allegro", "Check deployment status")

# Broadcast to all agents
await bridge.broadcast("System maintenance starting")

# Add message handler
def handle_message(msg):
    print(f"From {msg.sender}: {msg.content}")

bridge.add_handler(handle_message)

Convenience Functions

from agent.matrix_bridge import send_to_agent, broadcast_to_agents

# Send message
await send_to_agent("Ezra", "Review PR #456")

# Broadcast
await broadcast_to_agents("Going offline for maintenance")

Agent Registry

from agent.matrix_bridge import AgentRegistry

registry = AgentRegistry()

# Register agent with capabilities
registry.register("Timmy", capabilities=["code", "review", "deploy"])
registry.register("Allegro", capabilities=["monitoring", "alerting"])

# Find agents with capability
coders = registry.find_agents_with_capability("code")

Message Flow

┌─────────┐     ┌─────────┐     ┌─────────┐
│  Timmy  │────▶│ Matrix  │────▶│ Allegro │
│  Agent  │     │  Room   │     │  Agent  │
└─────────┘     └─────────┘     └─────────┘
     │               │               │
     │  [@Allegro]   │               │
     │  Check deps   │               │
     └──────────────▶│               │
                     │  [@Allegro]   │
                     │  Check deps   │
                     └──────────────▶│
                                     │
                     │  [@Timmy]     │
                     │  Done ✓       │
                     │◀──────────────┘
     │  [@Timmy]     │
     │  Done ✓       │
     │◀──────────────┘

Integration with Hermes

In run_agent.py

# Add to conversation loop
if self.matrix_bridge:
    # Check for messages from other agents
    messages = await self.matrix_bridge.get_pending_messages()
    for msg in messages:
        # Process agent-to-agent messages
        pass

In Gateway

# Add Matrix bridge to gateway
from agent.matrix_bridge import MatrixBridge

bridge = MatrixBridge(agent_name="Timmy")
await bridge.connect()
gateway.matrix_bridge = bridge

Testing

Unit Tests

def test_message_parsing():
    """Test message format parsing."""
    from agent.matrix_bridge import MatrixBridge
    
    bridge = MatrixBridge(agent_name="Timmy")
    
    # Test recipient extraction
    assert bridge._is_for_me("[@Timmy] Hello")
    assert not bridge._is_for_me("[@Allegro] Hello")
    assert bridge._is_for_me("[@*] Broadcast")
    
    # Test content extraction
    assert bridge._extract_content("[@Timmy] Hello") == "Hello"
    assert bridge._extract_content("[@*] Test message") == "Test message"

Integration Test

# Test with two agents
MATRIX_BRIDGE_ENABLED=true \
MATRIX_BRIDGE_ROOM=!test:matrix.example.org \
HERMES_AGENT_NAME=Timmy \
python -c "
import asyncio
from agent.matrix_bridge import send_to_agent

async def test():
    await send_to_agent('Allegro', 'Test message')
    print('Sent')

asyncio.run(test())
"

Troubleshooting

Bridge not connecting

1. Check MATRIX_BRIDGE_ENABLED=true
2. Verify MATRIX_BRIDGE_ROOM is set
3. Ensure Matrix credentials are configured
4. Check Matrix homeserver is reachable

Messages not received

1. Verify agent is in the Matrix room
2. Check message format: [@AgentName] content
3. Ensure HERMES_AGENT_NAME matches agent name
4. Check Matrix sync is running

Agent not found

1. Verify agent has joined the bridge room
2. Check agent name matches exactly (case-sensitive)
3. Ensure agent has announced presence

Related

• Issue #747: feat: multi-agent conversation bridge via Matrix
• Matrix Gateway: gateway/platforms/matrix.py
• Multi-Agent Orchestration: docs/multi-agent-orchestration.md