/orchestrating-agent-relay

name: orchestrating-agent-relay
description: The canonical way to run agent-relay - set up the Agent Relay core with `agent-relay init` 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.

> **The local broker was removed.** `agent-relay node up`, `node down`, > `node status`, `node metrics`, `node tail`, `node deadletters`, > `node redeliver` and `node agent …` now only print a removal notice. Run > `agent-relay init` to set up and start the Agent Relay core (or > `agent-relay init --hosted` for the hosted service), then spawn, list and > release agents through the relay MCP (`add_agent`, `list_agents`, > `remove_agent`) or the desktop app. Sections below that still mention the > broker, `node agent …`, `node tail` or `--state-dir` describe older releases.

Overview

A headless orchestrator is an agent that:

1. Makes sure the Agent Relay core is set up on this machine (`agent-relay init`; `agent-relay init --hosted` to use the hosted service instead) 2. Spawns and manages worker agents through the relay MCP 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. Spawning and releasing agents go through the same MCP (`add_agent` / `remove_agent`). 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 init` 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 | | Set up and start the core | `agent-relay init` (hosted: `agent-relay init --hosted`) | | Workspace + cloud status | `agent-relay status` | | Spawn worker (MCP) | `add_agent(name: "Worker1", cli: "claude", task: "...")` | | List workers (MCP) | `list_agents(status: "online")` | | 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` | | Release worker (MCP) | `remove_agent(name: "Worker1", reason: "...")` |

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: Set Up the Core

# Sets up and starts the Agent Relay core on this machine
agent-relay init

# Or use the hosted service so agents on other machines can join
agent-relay init --hosted

`agent-relay status` reports workspace and cloud login together. The CLI writes runtime state to `.agentworkforce/relay/` and may create `.mcp.json`; clean those files after validation if a worktree should remain clean.

Step 2: Spawn Workers

Spawn through the relay MCP (the orchestrating session runs `agent-relay mcp`):

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

> **Expect a 30–60s gap between spawn and the first ACK.** A worker shows in > `list_agents` within ~5s (the process is up), but the underlying CLI > (claude/codex) is still cold-starting and won't send its ACK DM until it > finishes booting — typically 30–45s, occasionally longer, after it appears. > Appearing in the list means "process alive," **not** "agent responsive." Don't > treat ACK silence in the first minute as a stuck worker; size ACK-wait loops > for at least 60s (e.g. a 30-iteration poll) befor