About Durable Agents

Durable Agents is a runtime and communication fabric for spawning and scaling collaborative agents on serverless compute, using your existing web and AI frameworks.

Agent sessions and communication are backed by Durable Streams. Each agent is an entity with its own stream of events.

Entities listen for messages and events. When a message or event is received, like a child finishing or state changing — the entity is woken and its handler runs.

All agent activity (runs, tool calls, text output) is persisted to the entity's durable stream. This means agents can scale to zero and survive restarts whilst maintaining full session history. Sessions can be observed and interacted with by any number of other users and entities both asynchronously and in real-time.

Entities

The unit of durable state. Defined with registry.define(). Each entity has a type and an ID, addressed by URL as /{type}/{id}. An entity's stream is the single source of truth for everything that has happened to it.

Handlers

The function that runs when an entity wakes. Receives a HandlerContext (ctx) and a WakeEvent (wake). The handler decides how to respond: configure an agent, update state, spawn children, or any combination.

Wakes

Events that trigger a handler invocation. Wake sources include: incoming messages, child entity completion, state changes, and timeouts. The wake event tells the handler why it was woken.

State

Custom persistent collections on the entity, written via ctx.db.actions and read via ctx.db.collections. Backed by TanStack DB. State is local to the entity and survives restarts. You define typed collections as part of the entity definition.

Agent loop

The core pattern is ctx.useAgent() followed by ctx.agent.run(). This runs the LLM in a loop — it generates text, calls tools, and continues until it has nothing left to do. All activity is automatically persisted to the entity's stream.

Tools

Functions the LLM can call during the agent loop. Each tool has a name, description, parameters (defined with TypeBox schemas), and an execute function. Tools run in the handler's context and have access to the entity's state and coordination primitives.

Coordination

Entities interact through structured primitives. An entity can spawn children, observe other entities, send messages, and share state. These operations are all durable — they survive restarts and are tracked in the event stream.

Built-in collections

Every entity automatically has collections for runs, steps, texts, tool calls, errors, inbox, and more. These are populated by the runtime as the agent operates. You can query them from the handler or observe them externally.