agent-unit weekly downloads statistics

agent-unit

Durable runs for any agent framework, on any host.

Write your agent with the AI SDK, Mastra, the OpenAI Agents SDK, LangGraph or plain TypeScript. agent-unit makes it durable without a rewrite, so it can pause for a human, sleep for a day, survive a crash and resume where it stopped, and deploys it to Node, Bun, Deno, Cloudflare, Vercel, Netlify or AWS Lambda. Every agent gets the same HTTP API, a resumable event stream, an MCP endpoint and an A2A agent card.

It is to agents what Nitro is to servers, and it is built on Nitro: one build and one runtime contract, with presets for every host.

• Durable without a rewrite. Model calls and tool calls are journaled automatically. When a run continues after a pause, a restart or a crash, completed work replays from the journal instead of running again, so the provider is not billed twice and a refund is not charged twice. • Pauses that cost nothing. run.interrupt() parks a run until someone answers, and run.sleep("2d") until a time passes. A parked run uses no compute, on any host. • One contract for every framework. The same run API, AG-UI events, manifest, MCP and A2A surface, whichever framework an agent uses, so a UI or an approvals inbox works with all of them. • No deployers to maintain. Framework authors write one small adapter; agent-unit and Nitro handle hosts, storage and scheduling.

Quick start

Every file in agents/ is an agent named after the file (agents/support/index.ts serves as support). Export a framework agent or a defineAgent agent as the default export.

Bring your framework

agent-unit recognises agents from these frameworks when your package.json depends on them:

| Framework | Export | What becomes durable | How it pauses |

| AI SDK | new ToolLoopAgent(…) or streamText settings | Every model call and tool call | useRun().interrupt() in a tool | | Mastra | new Agent(…) | Every model call and tool call (on a fork; your agent is untouched); memory uses the run's thread | Tool approvals (requireApproval, requireToolApproval), suspend() in a tool | | OpenAI Agents SDK | new Agent(…) | Model responses and function tools, per turn; handoffs included, handoff() options too | Tool approvals (needsApproval: true) | | LangGraph | graph.compile() | LangGraph checkpoints, stored in agent-unit storage | interrupt() in a node, resumed with Command({ resume }) | | Plain TypeScript | defineAgent(…) | run.step(…) | run.interrupt(), run.sleep() |

Every framework is tested on every host below (Node, Bun, Deno, Cloudflare Workers with Durable Objects, Vercel, Netlify and AWS Lambda): a run pauses for approval, the host restarts, and the resume repeats no model call or side effect.

Events follow AG-UI: text streams as TEXT_MESSAGE_*, a model's reasoning as REASONING_*, and RUN_FINISHED carries token usage per provider and model (also on the run as usage). An agent that asks for structured output (AI SDK output, Mastra structuredOutput, OpenAI Agents outputType) finishes with that object as its output.

A framework's own pauses become agent-unit interrupts, answered with POST /runs/:id/resume:

• Tool approvals (OpenAI Agents needsApproval, Mastra requireApproval or requireToolApproval) pause as tool-approval with { callId, tool, arguments, agent }. Answer true, false or { approved }; a declined call is not run and the model is told so. • Mastra suspend(payload) in a tool pauses under the tool's name with that payload. The answer becomes the tool's resumeData when it runs again, as with Mastra's own resume. • LangGraph interrupt(value) in a node pauses under the node's name; the answer resumes it.

When the run resumes, the model's first response comes from the journal, the tool call continues with the answer, and only new work reaches the provider.

Run primitives

Inside any run, useRun() (or the run argument of defineAgent) gives you:

| Primitive | |

| run.step(name, fn) | Run fn once; replays return the journaled result. fn receives { idempotencyKey } | | run.idempotencyKey() | The key of the step or tool call running now | | run.interrupt(name, payload) | Park until POST /runs/:id/resume answers, then return the answer | | run.sleep("10m") | Park until the time passes | | run.state.get/set/delete(key, { scope }) | State scoped to the thread (default), the agent or the app | | run.secrets.get(name) | Read a secret from the host environment (Workers bindings included) | | run.emit(name, value) | Emit a CUSTOM event | | run.signal | Aborts when the run is cancelled or parked |

The one rule: between steps, code must make the same decisions given the same journaled results. Put anything with side effects or randomness in a step. Model and tool calls already are.

A step is recorded when it finishes. If the process dies while a step is still running, that step runs again when the run recovers. Every step gets an idempotency key that stays the same when it runs again and differs for every other step and run; hand it to the API the step calls, and the repeat has no second effect:

Inside a tool the framework calls (AI SDK, Mastra, OpenAI Agents), useRun().idempotencyKey() returns the tool call's key. In a LangGraph node, wrap the side effect in useRun().step(…).

Deploy anywhere

| Host | Preset | Storage | Long runs | Sleep and recovery |…

Description from the npm listing.