quickstart.mdx

title	Quickstart
description	Launch your first agents in 2 minutes.

The Agent Relay SDK makes it super easy to integrate agent-to-agent communication into your existing application.

In order to use Agent Relay you'll need an agent like Claude Code, Codex, Gemini, or OpenCode already installed and running.

Install

Use your favorite package manager to install the SDK and embed it in your application.

```typeScript npm install @agent-relay/sdk ``` ```python pip install agent-relay-sdk ```

Simple example

Spawning a few agents and sending a kickoff message is super easy.

```typescript TypeScript file="agent.ts" import { AgentRelay, Models } from '@agent-relay/sdk';

const relay = new AgentRelay();

// Log messages as they flow between agents. relay.onMessageReceived = (msg) => { if (msg.text) { console.log(${msg.from} → ${msg.to}: ${msg.text}); } };

// Spawn three agents. const planner = await relay.claude.spawn({ name: 'Planner', model: Models.Claude.OPUS, }); const coder = await relay.codex.spawn({ name: 'Coder', model: Models.Codex.GPT_5_3_CODEX, }); const reviewer = await relay.opencode.spawn({ name: 'Reviewer', model: Models.Opencode.OPENAI_GPT_5_2, });

await Promise.all([ planner.waitForReady(), coder.waitForReady(), reviewer.waitForReady(), ]);

// Kick off the collaboration. await relay.system().sendMessage({ to: 'Planner', text: 'Collaborate with Coder and Reviewer to implement feature ID 7.', });

// Wait for everyone to finish, then shut down. await Promise.all([ planner.waitForIdle(), coder.waitForIdle(), reviewer.waitForIdle(), ]); await relay.shutdown();

```python Python file="agent.py"
import asyncio
from agent_relay import AgentRelay, Models

async def main():
    relay = AgentRelay()

    # Log messages as they flow between agents.
    relay.on_message_received = lambda msg: (
        print(f"{msg.from_name} → {msg.to}: {msg.text}")
        if msg.text else None
    )

    # Spawn three agents.
    planner = await relay.claude.spawn(
        name="Planner", model=Models.Claude.OPUS,
    )
    coder = await relay.codex.spawn(
        name="Coder", model=Models.Codex.GPT_5_3_CODEX,
    )
    reviewer = await relay.opencode.spawn(
        name="Reviewer", model=Models.Opencode.OPENAI_GPT_5_2,
    )

    await asyncio.gather(
        relay.wait_for_agent_ready("Planner"),
        relay.wait_for_agent_ready("Coder"),
        relay.wait_for_agent_ready("Reviewer"),
    )

    # Kick off the collaboration.
    await relay.system().send_message(
        to="Planner",
        text="Collaborate with Coder and Reviewer to implement feature ID 7.",
    )

    # Wait for everyone to finish, then shut down.
    await asyncio.gather(
        planner.wait_for_idle(),
        coder.wait_for_idle(),
        reviewer.wait_for_idle(),
    )
    await relay.shutdown()

asyncio.run(main())

CLI

If you want to run Agent Relay directly from the terminal instead of embedding the SDK in an app, install the CLI globally and start a local relay session.

Install agent-relay. The install script is the preferred option — it pulls the native broker binary for your platform along with the CLI.

```bash install script (recommended) curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash ``` ```bash npm npm install -g agent-relay ```

Start a local broker and spawn agents:

agent-relay up
agent-relay spawn planner claude "Break the work into steps"
agent-relay spawn coder codex "Implement the approved plan"
agent-relay send planner "Coordinate with coder and keep updates concise."
agent-relay who

See CLI Overview for the full command surface and Broker Lifecycle for running the local broker.

Let another agent orchestrate the team

If you want a host agent (Claude, Codex, or any CLI) to autonomously spawn and coordinate sub-agents from inside its own session, install the running-headless-orchestrator skill. It wires the agent-relay spawn / agent-relay dm commands into the host's tool surface so the host can run the team without leaving its session.

```bash prpm (recommended) # Install for a specific host npx prpm install @agent-relay/running-headless-orchestrator --as claude

Or install for multiple hosts at once

npx prpm install @agent-relay/running-headless-orchestrator --as claude,codex

```bash skills
npx skills add https://github.com/agentworkforce/skills --skill running-headless-orchestrator

Once installed, you can prompt the host like:

"Use the running-headless-orchestrator skill and spawn a claude agent called reviewer, DM it instructions, and wait for its verdict before you proceed."

The host uses the skill's tools to run agent-relay spawn reviewer claude ..., send DMs via agent-relay dm, and read replies — all without you touching the shell.