Agent Relay Orchestrator

Agent Relay Orchestrator

Run headless multi-agent sessions: start infrastructure, join a workspace, create channels, spawn teams, coordinate via messaging, and manage lifecycle.

Prerequisites

• agent-relay CLI installed (npm i -g agent-relay)
• Relaycast workspace key (rk_live_...) — get one at https://agentrelay.dev/openclaw or run agent-relay up to auto-create
• For Claude agents: ANTHROPIC_API_KEY or claude auth login

Quick Reference

Setup Flow

1. Join workspace (you, the orchestrator)

npx -y @agent-relay/openclaw@latest setup rk_live_YOUR_KEY --name orchestrator

This registers you on the workspace and configures mcporter for channel/DM tools.

2. Start broker with workspace key

agent-relay up --workspace-key rk_live_YOUR_KEY --no-spawn

Critical: Pass --workspace-key so spawned agents inherit the workspace connection. Without it, agents can't communicate via Relaycast channels.

3. Create channels for coordination

mcporter call relaycast create_channel name=my-project topic="Project coordination"
mcporter call relaycast join_channel channel=my-project

4. Spawn agents

agent-relay spawn architect claude --team my-team "Your task..."
agent-relay spawn developer claude --team my-team "Your task..."
agent-relay spawn tester claude --team my-team "Your task..."

Agent Communication

Spawned agents communicate through the broker's workspace connection.

From spawned agents (in their task prompt)

# Post to channel
agent-relay send '#channel-name' 'your message'

# DM another agent  
agent-relay send agent-name 'your message'

# Check inbox
agent-relay inbox

From orchestrator (via mcporter)

mcporter call relaycast post_message channel=my-project text="Status update"
mcporter call relaycast get_messages channel=my-project limit=20
mcporter call relaycast send_dm to=architect text="Review the design"

Agent Types

Task Prompt Template

Include communication instructions in every agent's task:

You are ROLE on the TEAM team.

## Communication
Post updates to #channel: agent-relay send '#channel' 'your message'
Check for messages: agent-relay inbox
DM a teammate: agent-relay send teammate-name 'message'

## Your Team
- agent-a (role) — does X
- agent-b (role) — does Y

## Tasks
1. ...
2. Post progress to #channel
3. When done: openclaw system event --text 'Done: description' --mode now

Monitoring

# Check all agents
agent-relay agents

# Tail an agent's output
agent-relay agents:logs NAME -n 500

# Check channel conversation
mcporter call relaycast get_messages channel=my-project limit=20

# Check who's online
mcporter call relaycast list_agents status=online

Lifecycle Management

# Kill a stuck agent
agent-relay agents:kill NAME

# Kill all agents in a team
agent-relay agents | grep TEAM | awk '{print $1}' | xargs -I{} agent-relay agents:kill {}

# Stop everything
agent-relay down

Rate Limiting

• Add 15s gaps between sequential spawns to avoid Relaycast 429 errors
• Use unique agent names per run (append UUID suffix) to avoid 409 conflicts
• The SDK uses registerOrRotate pattern: on 409, rotates the agent token

Common Patterns

Sequential pipeline

Spawn agent A → wait for completion → spawn agent B with A's output.

Parallel fan-out

Spawn N agents simultaneously, each on a subtask. Monitor via channel. Collect results.

Architect → Builder → Tester

1. Spawn architect to design
2. Architect posts to channel when done
3. Spawn builder to implement architect's design
4. Builder posts when done
5. Spawn tester to validate

Team with shared channel

All agents join same channel, post updates, read each other's work on a shared git branch.

Gotchas