orchestrating-agent-relay

name	orchestrating-agent-relay
description	The canonical way to run agent-relay - self-bootstrap the broker and autonomously spawn, monitor, and coordinate a team of worker agents without human intervention. Covers infrastructure startup, agent spawning, lifecycle monitoring, CLI-first reading, and team coordination.

Overview

A headless orchestrator is an agent that:

1. Starts the relay infrastructure itself (agent-relay up)
2. Spawns and manages worker agents
3. Monitors agent lifecycle events
4. Coordinates work without human intervention

The orchestrator drives the team from outside and is not a registered relay agent, so it reads/sends/lists via the agent-relay CLI (MCP mcp__relaycast__message_* tools require a registered identity). The workers it spawns are registered participants — their peer-messaging reference is the using-agent-relay skill.

When to Use

• Agent needs full control over its worker team
• No human available to run agent-relay up manually
• Agent should manage agent lifecycle autonomously
• Building self-contained multi-agent systems

Quick Reference

Step	Command/Tool
Verify installation	command -v agent-relay or npx agent-relay --version
Verify Node runtime if shim fails	node --version or fix mise/asdf first
Start infrastructure	agent-relay up --no-dashboard --verbose
Check status	agent-relay status --wait-for=10
Spawn worker	agent-relay spawn Worker1 claude "task"
List workers	agent-relay who
View worker logs	agent-relay agents:logs Worker1
Send DM to worker	agent-relay send Worker1 "message"
Post to channel	agent-relay send '#general' "message"
Read worker DM replies (full text)	agent-relay replies Worker1 (add --json to parse)
Read full DM conversation history	agent-relay history --to Worker1
Release worker	agent-relay release Worker1
Stop infrastructure	agent-relay down

Bootstrap Flow

Step 0: Verify Installation

# Check if agent-relay is available
command -v agent-relay || npx agent-relay --version

# If your shell reports a mise/asdf shim error, fix Node first
node --version
# e.g. for mise: mise use -g node@22.22.1

# If not installed, install globally
npm install -g agent-relay

# Or use npx (no global install)
npx agent-relay --version

Step 1: Start Infrastructure

# Starts a detached broker in headless mode and returns after API readiness
agent-relay up --no-dashboard --verbose

Step 2: Spawn Workers via MCP

mcp__relaycast__agent_add(
  name: "Worker1",
  cli: "claude",
  task: "Implement the authentication module following the existing patterns"
)

Step 3: Monitor and Coordinate

# Read Worker1's DM replies (chronological, full text, untruncated)
agent-relay replies Worker1

# Machine-readable: full text + direction, safe to parse in a loop
agent-relay replies Worker1 --json

# Send a targeted DM to a specific worker
agent-relay send Worker1 "Also add unit tests"

# Broadcast to all agents on a channel
agent-relay send '#general' "All workers: wrap up current task"

# List active workers (structured status for polling)
agent-relay who --json

Step 4: Release Workers

mcp__relaycast__agent_remove(name: "Worker1")

Step 5: Shutdown (optional)

agent-relay down

CLI Commands for Orchestration

replies --json schema (read this before writing a monitor)

[
  {
    "id": "01J...",
    "from": "Implementer",
    "to": "orchestrator",
    "text": "ACK — starting on the auth module",
    "createdAt": "2026-05-19T14:02:11.000Z",
    "direction": "inbound"
  }
]

Troubleshooting

# Kill unresponsive worker
agent-relay agents:kill Worker1

# Re-check broker status
agent-relay status

# If a worker looks stuck, inspect its logs first
agent-relay agents:logs Worker1

Orchestrator Instructions Template

Give your lead agent these instructions. The bootstrap/spawn/monitor commands

You are an autonomous orchestrator. Bootstrap the relay infrastructure
(Bootstrap Flow Steps 0–2), then spawn and manage workers per the
Quick Reference. Then enforce this protocol:

## Protocol
- Workers will ACK when they receive tasks — but expect a 30–60s cold-start
  gap after spawn: `who --json` shows `online` (~5s) well before the CLI is
  booted enough to send its first ACK. Don't troubleshoot a "stuck" fresh
  worker until at least 60s has passed
- Workers will send DONE when complete
- In a harnessed environment, never wait with a bare foreground `sleep`
  (it is blocked) — run ACK/DONE poll loops with run_in_background or a
  Monitor/until-loop, polling `replies --json` and `who --json` from inside it
- **ACK/DONE target: `orchestrator` (the auto-registered spawning identity) or
  the `#general` channel — NEVER `broker`.** `broker` is the broker's internal
  routing self-name, not a spawnable/DM-able agent: a worker DM to `broker` (and
  `agent-relay send broker`) fails with `Agent "broker" not found`. Write the
  worker task prompt to DM `orchestrator` (or post `#general`) — never "DM the
  broker"
- Tell every worker explicitly: do NOT self-remove/release after DONE — stay
  alive and idle so you can DM them review findings to fix
- After DONE, run a reviewer; on NO-GO, DM the findings back to the SAME
  worker. If the worker is gone, spawn a fresh one and re-inject branch +
  commit SHA + the full verdict
- Parse `replies --json` defensively: `direction` is always `"inbound"`,
  timestamp is `createdAt` (not `ts`), and the no-conversation state is a
  plain string, not `[]`
- Poll `agent-relay who --json` for worker liveness; set a wall-clock fallback
  so a silently-dead worker can't hang the loop
- Read worker DM replies with `agent-relay replies <name>` (`--json` to parse);
  plain `agent-relay history` shows channel posts only, never DM replies. See
  the "Channel vs DM" section for the full reading model

Multi-Round Review Loops (DONE → NO-GO → fix → re-review)

Workers must not self-remove until you tell them

Do NOT call agent.remove / agent-relay release on yourself. Report DONE and
stay alive and idle. The orchestrator will send you review findings to fix,
or release you when the work is fully accepted. Self-removing before then
breaks the fix loop.

The respawn-with-full-context fallback

agent-relay spawn Implementer2 codex "Continuation of prior work. \
Branch: feature/auth. Last commit: <sha>. \
The reviewer returned NO-GO with these findings: <full verdict text>. \
Check out the branch, address every finding, re-run tests, report DONE. \
Do NOT self-remove — stay alive for re-review."

Lifecycle Events

The broker emits these events (available via SDK subscriptions):

Event	When
agent_spawned	Worker process started
worker_ready	Worker connected to relay
agent_idle	Worker waiting for messages
agent_exited	Worker process ended
agent_permanently_dead	Worker failed after retries

Common Mistakes

Mistake	Fix
agent-relay: command not found or mise/asdf shim error	Ensure Node is available first (node --version); if a shim is broken, fix the runtime manager, then install/use agent-relay
"Nested session" error	Broker handles this automatically; if running manually, unset CLAUDECODE env var
Broker not starting	Try agent-relay down first, then agent-relay up --no-dashboard --verbose and agent-relay status --wait-for=10
Broker shows STARTING after status --wait-for	The process is alive but the broker API is not ready; inspect logs, retry readiness, or restart with agent-relay down --force if it remains stuck
Broker shows STOPPED immediately after start	Check ps aux | grep agent-relay-broker and .agent-relay/connection.json; if the process is alive but status is STOPPED, rerun status from the project root or pass --state-dir
Half-started broker: process alive but status says STOPPED and Failed to read broker connection metadata	up spawned a broker that never finished writing connection metadata (readiness timed out) and was not cleaned up. Do NOT just retry up — it won't reap the orphan. pkill -f agent-relay-broker (or agent-relay down --force), delete .agent-relay/, then agent-relay up clean and agent-relay status --wait-for=30. agent-relay doctor flags this orphaned/half-started state
Worktree verification leaves git status dirty	Run agent-relay down --force, then remove generated .agent-relay/ and .mcp.json from throwaway validation worktrees before committing
Spawn fails with internal reply dropped	Broker likely is not fully ready yet; wait for readiness, then spawn one worker first
Workers not connecting	Ensure broker started; check agent-relay who and worker logs

Overview

Self-bootstrap agent-relay infrastructure and manage a team of agents autonomously.

Prerequisites

1. agent-relay CLI installed (required)

npm install -g agent-relay
   # Or use npx without installing: npx agent-relay <command>