Skip to content
Tenzro
← All tutorials
Tutorial · Agents

Build an agent swarm orchestrator

Put a pool of member agents under one orchestrator, run tasks across them in parallel and track each member's status.

Advanced30 min

A swarm is a pool of member agents working for one orchestrator agent. The orchestrator creates the swarm, hands work to the members in parallel and collects their replies. Swarm membership and status are stored by the node, so a swarm survives a restart. Members are ordinary agents with their own lifecycle: one that stops sending heartbeats is suspended, and a swarm whose members have all stopped is marked completed.

Members are child agents of the orchestrator. Their authority can never be broader than the orchestrator's own delegation scope, so a swarm cannot spend more than the person who controls the orchestrator allowed.

Prerequisites

  • An orchestrator agent registered on the network, with its agent id. If you do not have one, create a delegated agent in /console/agents (see Create an agentic wallet) or register one with the CLI in step 1.
  • Node.js 20+ and npm install tenzro-sdk, or the tenzro CLI.
  • A chat model reachable for the orchestrator's reasoning loop: served by your node, or bought from the network.

1. Register the orchestrator

Skip this step if you already have an orchestrator agent id.

bash
tenzro agent register \
  --name review-orchestrator \
  --creator 0xYourAccount \
  --capabilities code,data \
  --rpc https://rpc.tenzro.xyz

The output includes the agent's id. Registration is an owner action signed by the creator account.

2. Create the swarm

The orchestrator id and a list of member specs (a name and capabilities each) define the swarm. The node spawns each member as a child agent of the orchestrator.

ts
import { TenzroClient } from "tenzro-sdk";

const client = new TenzroClient({ endpoint: "https://rpc.tenzro.xyz" });
const orchestratorId = process.env.ORCHESTRATOR_ID!;

const swarm = await client.agent.createSwarm(
  orchestratorId,
  [
    { name: "reviewer-security", capabilities: ["code"] },
    { name: "reviewer-performance", capabilities: ["code"] },
    { name: "reviewer-docs", capabilities: ["nlp"] },
  ],
  { max_members: 3, task_timeout_secs: 120, parallel: true },
);

console.log(swarm); // { swarm_id, orchestrator_id }

The same with the CLI:

bash
tenzro agent create-swarm \
  --orchestrator-id <orchestrator-id> \
  --members '[{"name":"reviewer-security","capabilities":["code"]},{"name":"reviewer-performance","capabilities":["code"]},{"name":"reviewer-docs","capabilities":["nlp"]}]' \
  --task-timeout-secs 120 \
  --parallel true \
  --rpc https://rpc.tenzro.xyz
OptionEffect
max_membersUpper bound on the swarm's size
task_timeout_secsHow long a member has to reply to a dispatched task
parallelDispatch to all members at once (true, the default) or one after another

3. Run work through the orchestrator

Give the orchestrator a task. It runs an agentic loop on a chat model, with built-in tools to spawn agents, delegate tasks, collect results and complete, and uses them to fan the work out to its members and merge what comes back.

ts
const run = await client.agent.runAgentTask(
  orchestratorId,
  "Review the diff at https://example.com/pr/42.patch for security, performance and documentation issues. " +
    "Give each reviewer one area, then merge their findings into one list ordered by severity.",
);
console.log(run);

Any payment a member makes in the process, such as buying inference, is checked against its own scope and, through the parent chain, against the orchestrator's.

4. Poll the swarm

getSwarmStatus returns the swarm's lifecycle status (idle, working or completed) and each member's state and result:

ts
const status = await client.agent.getSwarmStatus(swarm.swarm_id);

console.log(status.status, status.member_count);
for (const m of status.members) {
  console.log(m.agent_id, m.role, m.status, m.result?.slice(0, 80));
}
bash
tenzro agent get-swarm --swarm-id <swarm-id> --rpc https://rpc.tenzro.xyz

List every swarm on the node with tenzro_listSwarms:

bash
curl -s https://rpc.tenzro.xyz -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tenzro_listSwarms","params":[]}' | jq

5. Terminate the swarm

Terminating a swarm stops its member agents and releases the swarm's state. The orchestrator stays registered and can create a new swarm.

ts
const done = await client.agent.terminateSwarm(swarm.swarm_id);
console.log(done); // { swarm_id, status: "terminated" }
bash
tenzro agent terminate-swarm --swarm-id <swarm-id> --rpc https://rpc.tenzro.xyz

The controller of the orchestrator can also pause, quarantine or terminate the orchestrator itself; terminating with cascade ends every descendant, members included.

Next steps