SDK

The swarmlord TypeScript client.

A single package, works in Node, Bun, the browser, and edge runtimes.

npm install swarmlord

Create a client

import { createClient } from "swarmlord";

const client = createClient({
  apiKey: process.env.SWARMLORD_API_KEY!,
  // baseUrl defaults to https://api.swarmlord.ai
});

Talk to an agent

const session = await client.agent("hello-agent").createSession();

const { value, degraded } = await session
  .send({ parts: [{ type: "text", text: "Say hi." }] })
  .result<string>();

result() resolves on the first terminal event. degraded is true if there were retries.

Stream

for await (const ev of session.stream({ parts: [{ type: "text", text: "Hi" }] })) {
  if (ev.type === "part.appended" && ev.part.type === "text") {
    process.stdout.write(ev.part.text);
  }
  if (ev.type === "session.completed") break;
}

Multi-turn

await session.send({ parts: [{ type: "text", text: "My name is Ada." }] }).result();
await session.send({ parts: [{ type: "text", text: "What's my name?" }] }).result();
// → "Your name is Ada."

Structured output

Use Zod to validate the reply:

import { z } from "zod";

const Recipe = z.object({
  title: z.string(),
  servings: z.number(),
  ingredients: z.array(z.object({ item: z.string(), quantity: z.string() })),
});

const { value: text } = await session
  .send({ parts: [{ type: "text", text: "Reply with carbonara as strict JSON." }] })
  .result<string>();

const recipe = Recipe.parse(JSON.parse(text));

Reconnect to a known session

const session = client.session("25e8755c-ed87-4bcd-95fa-3963068e5c1a");

Resume with replay

import { streamSession } from "swarmlord";

const stream = streamSession(sessionId, {
  opts: { apiKey },
  sinceSeq: lastSeen,
});

for await (const ev of stream) {
  if (ev.type === "session.completed") break;
}

Abort

await session.abort();

Verify incoming webhooks

import { verifyWebhook } from "swarmlord/webhooks";

const ok = await verifyWebhook({
  secret: process.env.SWARMLORD_WEBHOOK_SECRET!,
  signature: req.headers.get("x-swarmlord-signature")!,
  body: await req.text(),
});

Types

import type { AgentEvent, Part, Terminal } from "swarmlord";

See the HTTP reference for the raw wire protocol and Events for the full event vocabulary.