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.com/openclaw or run agent-relay up to auto-create
• For Claude agents: ANTHROPIC_API_KEY or claude auth login

Quick Reference

Action	Command
Start broker	agent-relay up --workspace-key rk_live_KEY --no-spawn
Start broker (background)	agent-relay up --workspace-key rk_live_KEY --background --no-spawn
Check status	agent-relay status
Spawn agent	agent-relay spawn NAME CLI "task"
Spawn with team	agent-relay spawn NAME CLI --team TEAM "task"
List agents	agent-relay agents
View logs	agent-relay agents:logs NAME
Send to channel	agent-relay send '#channel' 'message'
Send DM	agent-relay send AGENT 'message'
Kill agent	agent-relay agents:kill NAME
Stop broker	agent-relay down

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

CLI	Use For	Notes
claude	Most reliable for coding tasks	--print --permission-mode bypassPermissions under the hood
droid	OpenCode-based, needs PTY	Don't use --cwd flag (broker can't auto-accept permission prompts — see PR #570)
gemini	Google models	Use gemini-2.5-pro (not preview) for stability
codex	OpenAI Codex	Requires PTY

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

Issue	Fix
Agents can't message	Broker must have --workspace-key
Droid stuck at approval	Don't use --cwd with droid agents
Agent name conflict (409)	Use unique names or let SDK registerOrRotate handle it
Channel not found	Create it first via mcporter call relaycast create_channel
Agent idle but no output	Check agent-relay agents:logs NAME for errors
npx setup fails in spawned agent	Agents inherit broker's workspace — no setup needed
agent-relay send fails for DM	Spawned agents can broadcast to channels but DMs may not work for non-Relaycast-registered agents