agentworkforce/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 |