runstate-sdk

TypeScript SDK for runstate, the coordination layer for agent swarms. Wrap a function once where you define it, then call it exactly as before. runstate does the coordination inside the call: work done once per run, shared rate limits, slots, budgets, queues and stopping a run.

Published as runstate-sdk on npm, matching the Python package runstate-sdk on PyPI.

Install

npm install runstate-sdk

Requires Node.js 22 or later.

Configure

Set these in the environment:

export RUNSTATE_API_KEY=<your api key>
export RUNSTATE_SPACE_ID=<your space id>
export RUNSTATE_RUN=nightly               # optional, default "default"
# export RUNSTATE_BASE_URL=http://localhost:8080   # optional, default https://api.getrunstate.com

The SDK reads them on the first call. Importing it makes no network calls. To configure in code, use runstate.configure({ apiKey, spaceId, run }) or new Runstate({ ... }).

Use

import runstate from 'runstate-sdk';

const research = runstate.once(researchCompany);                  // once per run for the same arguments
const search = runstate.limit('search-api', searchWeb, { max: 60, per: 'minute' });
const browse = runstate.slots('browser', openPage, { max: 5 });
const ask = runstate.budget('model-usd', callModel, { reserve: 0.4, cost: (r) => r.usd, limit: 50 });

await research('acme');   // looks like a normal call
await runstate.stop();    // every worker stops taking new work

Hand work to workers

// review.ts, imported by producers and workers
export const review = runstate.queue('review', async (doc: Doc) => scoreDoc(doc), { slots: 'browser' });

// producer
const score = await review(doc);
const accepted = await review.gather(docs, { need: 5, accept: (r) => r.score > 0.8 });

// worker
await runstate.serve();

Durations are seconds or strings such as '30s' and '10m'. Every error is a RunstateError; see the docs for the full list.

Docs

• Reference: https://docs.getrunstate.com/sdk/typescript/
• Migrating from 0.2: https://docs.getrunstate.com/changelog/
• HTTP API for other languages: https://docs.getrunstate.com/api/

License

MIT