Spawning an agent

Spawn an agent on the relay deterministically or dynamically.

Spawning starts an agent "on the relay" and returns an Agent handle you can wait on, message, observe, and release later.

Spawn

spawn-agent.ts

import { AgentRelay, Models } from '@agent-relay/sdk';

const relay = new AgentRelay({ channels: ['dev'] });

const planner = await relay.claude.spawn({
  name: 'Planner',
  model: Models.Claude.SONNET,
  channels: ['dev'],
  task: 'Break the work into 3 implementation steps.',
});

Spawned agents are either headless (Claude Code, OpenCode) or PTY-backed (Codex, Gemini all others). Agent Relay ensures that messages are routed and injected into the agent's runtime as needed.

Agents can also spawn other agents via the CLI or MCP.

Dynamic spawn

dynamicspawn.ts


const cli = 'claude';

const reviewer = await relay.spawn(
  'Reviewer',
  cli,
  'Review the migration plan and list the highest-risk steps.',
  {
    channels: ['review'],
    model: 'sonnet',
    cwd: '/repo',
  }
);

Named Spawn

spawners.ts

const claudeWorker = await relay.claude.spawn({ name: 'Planner' });
const codexWorker = await relay.codex.spawn({ name: 'Coder' });
const geminiWorker = await relay.gemini.spawn({ name: 'Researcher' });
const opencodeWorker = await relay.opencode.spawn({ name: 'Reviewer' });

Relay startup options

These options control how the local broker/client is started before any agents are spawned:

Option	What it does
`binaryPath`	Path to the agent-relay-broker binary. Auto-resolved if omitted.
`binaryArgs`	Extra args passed to `broker init` (for example `{ persist: true }`).
`brokerName`	Broker name. Defaults to the current working directory basename.
`channels`	Default channels for spawned agents.
`cwd`	Working directory for the broker process.
`env`	Environment variables for the broker process.
`onStderr`	Forward broker stderr lines to this callback.
`startupTimeoutMs`	Timeout in ms to wait for the broker to become ready. Defaults to `15000`.
`requestTimeoutMs`	Timeout in ms for HTTP requests to the broker. Defaults to `30000`.

Per-agent spawn options

These options are available on the shorthand helpers and on relay.spawn(...):

Option	What it does
`name`	Stable identity other agents can message
`model`	Model string or enum for that provider
`task`	Initial prompt for autonomous startup
`channels`	Rooms the agent joins on spawn
`args`	Extra CLI arguments
`cwd`	Per-agent working directory override
`skipRelayPrompt`	Skip MCP/protocol prompt injection when relay messaging is not needed
`onStart`	Run code before spawn
`onSuccess`	Run code after a successful spawn
`onError`	Run code if spawn fails