Swarm

Defined in: src/multiagent/swarm.ts:97

Swarm multi-agent orchestration pattern.

Agents execute sequentially, each deciding whether to hand off to another agent or produce a final response. Routing is driven by structured output: each agent receives a Zod schema with agentId, message, and optional context fields. When agentId is present, the swarm hands off to that agent with message as input. When omitted, message becomes the final response.

Key design choices vs the Python SDK:

• Handoffs use structured output rather than an injected handoff_to_agent tool. Routing logic stays in the orchestrator, not inside tool callbacks.
• Context is passed as serialized JSON text blocks rather than a mutable SharedContext.
• A single maxSteps limit replaces Python’s separate max_handoffs/max_iterations.
• Agent descriptions are embedded in the structured output schema for routing decisions.
• Exceeding maxSteps throws an exception. Python returns a FAILED result.

Example

const swarm = new Swarm({
  nodes: [researcher, writer],
  start: 'researcher',
  maxSteps: 10,
})

const result = await swarm.invoke('Explain quantum computing')

Implements

• MultiAgentBase

Constructors

Constructor

new Swarm(options): Swarm;

Defined in: src/multiagent/swarm.ts:106

Parameters

Parameter	Type
options	SwarmOptions

Returns

Swarm

Properties

id

readonly id: string;

Defined in: src/multiagent/swarm.ts:98

Unique identifier for this orchestrator.

Implementation of

MultiAgentBase.id

---

config

readonly config: Required<SwarmConfig>;

Defined in: src/multiagent/swarm.ts:99

---

hooks

readonly hooks: HookRegistry;

Defined in: src/multiagent/swarm.ts:100

Methods

initialize()

initialize(): Promise<void>;

Defined in: src/multiagent/swarm.ts:131

Initialize the swarm. Invokes the MultiAgentInitializedEvent callback. Called automatically on first invocation.

Returns

Promise<void>

---

invoke()

invoke(input): Promise<MultiAgentResult>;

Defined in: src/multiagent/swarm.ts:143

Invoke swarm and return final result (consumes stream).

Parameters

Parameter	Type	Description
input	InvokeArgs	The input to pass to the start agent

Returns

Promise<MultiAgentResult>

Promise resolving to the final MultiAgentResult

Implementation of

MultiAgentBase.invoke

---

stream()

stream(input): AsyncGenerator<MultiAgentStreamEvent, MultiAgentResult, undefined>;

Defined in: src/multiagent/swarm.ts:159

Stream swarm execution, yielding events as agents execute. Invokes hook callbacks for each event before yielding.

Parameters

Parameter	Type	Description
input	InvokeArgs	The input to pass to the start agent

Returns

AsyncGenerator<MultiAgentStreamEvent, MultiAgentResult, undefined>

Async generator yielding streaming events and returning a MultiAgentResult

Implementation of

MultiAgentBase.stream