Swarm

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

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

• MultiAgent

Constructors

Constructor

new Swarm(options): Swarm;

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

Parameters

Parameter	Type
options	SwarmOptions

Returns

Swarm

Properties

id

readonly id: string;

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

Unique identifier for this orchestrator.

Implementation of

MultiAgent.id

---

nodes

readonly nodes: ReadonlyMap<string, AgentNode>;

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

---

config

readonly config: Required<SwarmConfig>;

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

---

start

readonly start: AgentNode;

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

Methods

initialize()

initialize(): Promise<void>;

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

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

Returns

Promise<void>

---

addHook()

addHook<T>(eventType, callback): HookCleanup;

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

Register a hook callback for a specific swarm event type.

Type Parameters

Type Parameter
T extends HookableEvent

Parameters

Parameter	Type	Description
eventType	HookableEventConstructor<T>	The event class constructor to register the callback for
callback	HookCallback<T>	The callback function to invoke when the event occurs

Returns

HookCleanup

Cleanup function that removes the callback when invoked

Implementation of

MultiAgent.addHook

---

invoke()

invoke(input): Promise<MultiAgentResult>;

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

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

MultiAgent.invoke

---

stream()

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

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

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

MultiAgent.stream