SDKSDK overview

The SDK

Anything your AI does with Swarm, your own code can do. @swarm-agent/sdk is the typed TypeScript client: chat with streaming, agents in your apps, triggers for your workers, and the signal feed.

hello.ts

import { SwarmClient } from '@swarm-agent/sdk';

// On the machine: no token needed.
const swarm = new SwarmClient();

const box = await swarm.box.summary();
box.status;  // "ok"

await swarm.workers.trigger({ worker_id });

swarm.chatswarm.agentsswarm.workersswarm.automationsswarm.signalsswarm.box

Install

Shell

npm install @swarm-agent/sdk

Node 22 or newer, ESM. In browser code use @swarm-agent/sdk/browser, and never give a browser a Swarm token: tokens stay on your server.

Connect

On the Swarm machine

new SwarmClient() finds the owner socket when your program runs as the user that runs Swarm. No token.

From anywhere else

new SwarmClient({ baseUrl, token }), or SWARM_API_URL and SWARM_AUTH_TOKEN in the environment.

In a browser

Talk to your own server, which holds the token. Only @swarm-agent/sdk/browser, never a token.

Which key

Every key reaches only what its job needs. Pick the smallest one:

Key	For	Can
Owner socket	A program on the machine, running as the user that runs Swarm	Everything. No token needed.
Client key	A backend that talks to sessions	Session routes only.
Trigger token	Your webhook, CI or app	Start one worker. Nothing else.
Gateway token	The server behind a custom agent	That one sealed agent’s conversations and tool calls.
Monitor key	A dashboard	Read status and signals.
AI key	Your AI	The MCP tools only, not the SDK routes.

What's in it

swarm.chat

Sessions you talk to, with live streaming text and tool events.

swarm.agents

Sealed agents for your own apps, their client tools and gateway tokens.

swarm.workers

Workers of your own: define, deploy, trigger, list their runs.

swarm.automations

Schedules and triggers attached to workers.

swarm.signals

The machine’s signal feed and signed delivery to your endpoints.

swarm.box

One call: is this machine ok, attention or degraded, and why.

swarm.sessions

Create, message, wait for and archive sessions.

swarm.projects

Projects, their folders and their conversations.

Chat with streaming

chat.ts

const session = await swarm.chat.createSession({ title: 'Release notes' });

const watch = await swarm.chat.stream(session.id, {
  onText: (text) => process.stdout.write(text),     // never repeated or skipped
  onToolStarted: (tool) => console.log('\n→', tool.name),
  onComplete: () => watch.dispose(),
});

await swarm.chat.sendMessage(session.id, 'Write release notes for the last 10 commits.');

The stream reconnects on its own and never repeats or skips text. For scripts, swarm.chat.run sends a message and waits for the finished reply.

Trigger a worker

ci.ts

// With a token that can only start this worker:
const run = await swarm.workers.trigger({
  worker_id: process.env.WORKER_ID,
  payload: { build: ci.buildId, failed: ci.failedTests },
  idempotency_key: ci.buildId,
});
console.log(run.id, run.status);

The worker runs its standing instructions with your payload as context. More in Workflows.

Watch the machine

watch.ts

// Every high-level event on the machine, read with a cursor.
let after = 0;
const page = await swarm.signals.list({ after });
for (const s of page.signals) console.log(s.severity, s.kind, s.summary);
after = page.next_after;

swarm.box.summary() answers “is it OK?” in one call; swarm.signals.sinks.create sends the feed to your endpoint, signed. See Alerts.

Agents in your apps

A sealed agent answers your visitors and can only call the tools your app defines. That has its own page: Custom agents.

Errors

Error	When
`SwarmAuthError`	401: no token, or a dead one.
`SwarmForbiddenError`	403: the token may not do that.
`SwarmNotFoundError`	404: no such session, worker or agent.
`SwarmConflictError`	409: someone changed it first; read it again.
`SwarmTimeoutError`	A wait ran out.

errors.ts

import { SwarmAuthError, SwarmForbiddenError, SwarmNotFoundError } from '@swarm-agent/sdk';

try {
  await swarm.workers.trigger({ worker_id });
} catch (err) {
  if (err instanceof SwarmForbiddenError) { /* this token may not do that */ }
}

Or call the tools directly

Everything your AI uses is an MCP server on the machine (port 7783, path /mcp). Every tool is one stateless JSON-RPC call with the AI key, so any language can drive Swarm the way your AI does:

POST /mcp

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"swarm_give_job","arguments":{"worker":"coder","project":"PROJECT_ID","brief":"Fix the failing tests"}}}

The full reference, current limits and every method: ai/sdk.md, the package README, and the source at github.com/swarm-agent/swarm.