/orchestrating-agent-relay

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

Orchestrating Agent Relay

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

Overview

A headless orchestrator is an agent that:

1. Starts the local relay broker itself (`agent-relay node up`) 2. Spawns and manages worker agents on that broker 3. Monitors agent lifecycle events 4. Coordinates work without human intervention

The orchestrator drives the team and reads/sends/lists through the **Agent Relay MCP server** (`agent-relay mcp`). The session registers itself once with the `register_agent` tool (name it `orchestrator`) — every messaging tool errors with `Not registered. Call the "register_agent" tool first.` until it does. Lifecycle control — starting the broker, spawning/releasing local agents, streaming broker debug events — goes through the `agent-relay node` command group. The workers it spawns are registered participants too; their peer-messaging reference is the **`using-agent-relay`** skill.

The model

• Agent Relay delivers messages **node-only**: every agent is owned by a node,

and the engine routes that agent's messages to its node reliably (ordered, resumable). The local broker is a node; agents you spawn on it are bound to it.

• A **fleet** is the set of nodes advertising **capabilities** (`spawn:<harness>`

plus custom node actions). The engine **places** a spawn or action onto a node by capability + liveness + capacity + least-loaded, or onto a named `target_node`. Spawning and releasing agents are actions. Most orchestration spawns on the local broker; fleets matter when coordinating across nodes.

• Agent-to-agent coordination is messages — channels, DMs, threads — plus

reactions and read receipts. Reading another agent's replies is a messaging operation (`check_inbox`, `list_messages`, `get_message_thread`), **not** a broker-event tail.

When to Use

• Agent needs full control over its worker team
• No human available to run `agent-relay node 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 broker | `agent-relay node up --background --verbose` | | Check broker readiness | `agent-relay node status --wait-for 10` | | Workspace + cloud + broker status | `agent-relay status` | | Spawn worker | `agent-relay node agent spawn claude --name Worker1 --task "..."` | | List workers | `agent-relay node agent list` | | Resource usage | `agent-relay node metrics` | | Send DM to worker (MCP) | `send_dm(to: "Worker1", text: "...")` | | Post to channel (MCP) | `post_message(channel: "general", text: "...")` | | Read worker replies (MCP) | `check_inbox(limit: 20)` / `list_messages(channel: "general")` | | Give a human a follow-along link | `agent-relay observer` | | Inspect a worker's TTY | `agent-relay node agent attach Worker1 --mode view` | | Release worker | `agent-relay node agent release Worker1` | | Stop broker | `agent-relay node 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 the Broker

# Starts a detached broker and returns after API readiness
agent-relay node up --background --verbose

Verify broker readiness before spawning any workers:

# Polls for readiness; must report the daemon running before you spawn workers
agent-relay node status --wait-for 10

`agent-relay status` (top level) reports workspace, cloud login, and local broker status together; `agent-relay node status` is the focused broker-daemon readiness check.

> The broker/agent lifecycle commands live under `agent-relay node …`. The old > flat `agent-relay local …` group still works as a **hidden, deprecated alias** > and prints a removal warning — use `node` in new work.

When verifying from a source checkout or throwaway git worktree, run these commands from the project/worktree root. The CLI writes runtime state to `.agentworkforce/relay/` and may create `.mcp.json`; clean those files after validation if the worktree should remain clean.

The broker:

• Auto-creates a Relaycast workspace if no workspace key is set
• Removes the `CLAUDECODE` env var when spawning (fixes nested session error)
• Persists state to `.agentworkforce/relay/` (broker connection metadata,

lock/pid, and `.agentworkforce/relay/connection.json`)

Step 2: Spawn Workers

The orchestrator's MCP session can sp