How Durable Agents Work

View as MarkdownView as Markdown

Your framework still runs the agent: its prompts, tools, and model choice stay the same. Dex runs each conversation as one session Flow, and each model call and tool call in it as a Step. Dex records every Step's result, so a crash, a deploy, or a long wait repeats nothing that finished.

YOUR APP

ClientRun the agentsend_user_message

message

message

THREAD → SESSION FLOW

AGENT LOOP → STEPS

LLM callRunModel→Tool callCallTool→Human in the loopAwaitToolApproval→Tool resultsResumeTurn

Chat historyAttributesStreamingAgentEvents Stream

Chip: your framework. Below: Dex.

calls

calls

Models

Tools

Your framework's terms in Dex

In your framework	In Dex	What changes for you
Agent	Your agent, wrapped by a Dex adapter into a session Flow	Prompts, tools, and model choice stay as they are.
Thread, conversation, session	A session: one Flow run. The Flow ID is the session ID.	The session survives crashes and deploys. After it stops, it stays readable for the retention period.
Run the agent	The send_user_message RPC from a Client (sendUserMessage in TypeScript)	Dex records the message before the turn starts. A message sent during a turn waits in a queue.
Turn	A turn: the Steps from one user message to the reply	Steer (steer_user_message) ends a turn at the next safe Step boundary. cancel_turn also stops a running model call and drops its answer. Neither stops a tool call that has started.
LLM call	A RunModel Step	Dex records the response. A retry calls the model again.
Tool call, function call	A CallTool Step for a read or an idempotent write, a CallSingleAttemptTool Step for any other write	A write in its own Step runs at most once. When a crash leaves its result unknown, the model sees outcome_unknown.
Parallel tool calls	Tool Steps that run in parallel, then a ResumeTurn Step	ResumeTurn waits for every result and gives them to the model.
Human in the loop, tool confirmation	An AwaitToolApproval Step, answered with the resolve_interrupt RPC (resolveInterrupt in TypeScript) or in Dex Web	The wait can last days and holds no Worker.
Checkpointer, durable execution plugin	Recorded Step results. The adapter keeps the framework's own state between Steps.	A crash repeats only the Step that was running. The agent code needs no determinism rules.
Chat history, short-term memory	The session's Attributes	Long-term memory across sessions stays in a store you own, behind a tool.
Streaming callbacks	The AgentEvents Stream	It is best effort. get_agent_snapshot (getAgentSnapshot in TypeScript) reads the recorded conversation.
MCP servers, tool integrations	Tool sources. Official Connectors come in through ConnectorToolSource.	Each Connector call gets its credentials and an idempotency key.

Some tools run inside RunModel or at the model provider, and they can run again when that Step retries. Examples are reads and CLI tools such as Bash in the Claude Agent SDK, hosted tools, and tools that Mastra runs itself. A LangGraph graph can also make several model calls in one RunModel. Framework Support lists the differences.

Sessions

A session holds one conversation: its messages, its tool calls, and their results. It waits for the next message without using a Worker. Each Step is saved before the session moves on, which adds about a tenth of a second per Step. A new session starts empty.

Sessions in depth covers latency, cost, and memory.

Tool calls

Each tool gets a policy. Its effect class says what a repeat would do: a read and an idempotent_write can run again, and any other write runs at most once. Every attempt of a call gets the same idempotency key. Pass it to the service the tool writes to.

Tool Calls in depth covers each outcome and how to reconcile an unknown one.

Approvals

A tool call that needs approval waits in AwaitToolApproval until a person answers. By default, a write that is not idempotent waits for approval. A person approves or rejects the call from your application or in Dex Web, and the model sees a rejection.

Approvals in depth covers the RPC, Dex Web, and approval deadlines.

Connectors as tools

An agent can call official Connector operations as tools. The Connector's manifest sets each operation's effect class, and the application picks the operations to offer. Each call runs in its own tool Step with the Connector's credentials.

Connectors as Tools in depth covers the wiring for each framework.

Next

• Run Agents in Production: the checklist before you run sessions for real users.
• Built-in Agent Loop: the harness with questions, plans, and durable waits.