Spawning an agent

Spawn an agent on the relay deterministically or dynamically, configuring its harness, identity, and runtime so it can join your multi-agent workspace.

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.spawnAgent({
  name: 'Planner',
  cli: 'claude',
  model: Models.Claude.SONNET,
  channels: ['dev'],
  task: 'Break the work into 3 implementation steps.',
});

Spawned agents are either PTY-backed terminal sessions or headless app-server sessions. 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.spawnAgent({
  name: 'Reviewer',
  cli,
  task: 'Review the migration plan and list the highest-risk steps.',
  channels: ['review'],
  model: 'sonnet',
  cwd: '/repo',
});

Common configs

spawners.ts

const claudeWorker = await relay.spawnAgent({ cli: 'claude' });
const codexWorker = await relay.spawnAgent({ cli: 'codex' });
const geminiWorker = await relay.spawnAgent({ cli: 'gemini' });
const opencodeWorker = await relay.spawnAgent({
  cli: 'opencode',
  runtime: 'headless',
});

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 TypeScript relay.spawnAgent(...) configs and Python spawn helpers:

Option	What it does
`name`	Stable identity other agents can message. Defaults from `cli`.
`cli`	CLI or named harness to spawn
`runtime`	Runtime category. Defaults to `pty`; set `headless` for app-server sessions
`model`	Model string or enum for the selected CLI
`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

Structured results

TypeScript spawns can include a result contract. Agent Relay exposes a submit_result MCP tool to the spawned agent, then routes the submitted JSON back through agent.waitForResult(...), the per-spawn onResult callback, and relay.addListener('agentResult', ...).

spawn-with-result.ts

import { z } from 'zod';

const Result = z.object({
  decision: z.enum(['approve', 'request_changes']),
  notes: z.array(z.string()),
});

const reviewer = await relay.spawnAgent({
  name: 'Reviewer',
  cli: 'claude',
  task: 'Review the change and submit your decision as structured JSON.',
  result: { schema: Result },
});

const { data } = await reviewer.waitForResult(120_000);
console.log(data.decision);