runstate docs

Once you run more than a handful of agents in parallel, they start stepping on each other: two agents do the same task, fifty agents hit the same API and retry together, the swarm overspends overnight, and work disappears when a worker crashes.

runstate is a hosted service with TypeScript and Python SDKs that holds the state your agents need to agree on: who owns a piece of work, what its result was, how much of a shared quota is left, how much budget is committed, and whether the run is done. It keeps that state correct when individual agents crash, restart or run late.

runstate does not run your agents, call your models or sit in your request path. Your agents, prompts and frameworks stay where they are, and they call runstate at the points where they need to coordinate.

Start here

QuickstartSubmit a task from one process, finish it in another, and read back its durable result. About ten minutes.

ConceptsRuns, work queues, tasks, claims and leases: the handful of ideas every guide builds on.

Guides

Each guide covers one problem teams hit when they go from one agent to many, in the order most teams run into them.

Claims, shared tasks and takeoverOwnership of a key, shared tasks with one recorded result, and takeover when a worker dies.

Quotas and concurrency poolsShared quotas, concurrency pools and admission, so agents wait their turn instead of stampeding.

Spend budgetsReserve spend before expensive work, settle the real cost, release the rest.

Task groups and cancellationDecide once when the work is done, and stop handing out new work across the whole run.

Events and monitoringThe console, the event journal, live watch and diagnostics.

LangGraph and OpenAI Agents SDKUse runstate inside LangGraph and the OpenAI Agents SDK.

Reference

TypeScript SDKEvery class and method in runstate-sdk for Node 22 and later.

Python SDKAsyncRunstate and the blocking Runstate client, with the differences from TypeScript called out.

HTTP APIEvery endpoint, generated from the OpenAPI document.

Errors & retriesEvery error code, its HTTP status, and what the SDKs retry for you.

What it looks like

A few calls inside the agent code you already have:

TypeScript

import { Runstate } from 'runstate-sdk';

const rs = new Runstate(); // reads RUNSTATE_API_KEY, RUNSTATE_SPACE_ID, RUNSTATE_BASE_URL
const run = await rs.scopes.create(); // one run of your swarm

// Only one agent works on Acme at a time. A crashed owner's lease expires.
await run.claim('company:acme').run(async () => {
  await researchCompany('acme');
});

// Every agent draws from one search-API quota and waits its turn.
await run.quota('search-api').take();

// One spend ceiling for the whole swarm.
const spend = await run.budget('research-usd').reserve({ amount: '0.40' });
const cost = await callExpensiveModel();
await spend.settle({ amount: cost.usd, usageKey: cost.requestId });

Python

from runstate import AsyncRunstate

rs = AsyncRunstate()  # reads RUNSTATE_API_KEY, RUNSTATE_SPACE_ID, RUNSTATE_BASE_URL
run = await rs.scopes.create()  # one run of your swarm


async def research(lease):
    await research_company("acme")


# Only one agent works on Acme at a time. A crashed owner's lease expires.
await run.claim("company:acme").run(research)

# Every agent draws from one search-API quota and waits its turn.
await run.quota("search-api").take()

# One spend ceiling for the whole swarm.
spend = await run.budget("research-usd").reserve(amount="0.40")
cost = await call_expensive_model()
await spend.settle(amount=cost.usd, usage_key=cost.request_id)

The quota and budget in this example are created once with rs.quotas.ensure() and rs.budgets.ensure(); the guides show the full setup.

Status

runstate is in a private developer preview: free, invite-only, and without an SLA. The hosted service runs in a single EU region. Request access to get a space and API keys.

For agents and LLM tools, this site is also available as llms.txt, and every page has a Markdown version (add .md to the path, or use Copy page).