---
title: "Sessions"
description: "A durable agent session is one Flow run that holds one conversation. Each model call and each tool call runs in a Step. So a crash, a deploy, or a long wait repeats nothing that already finished."
canonical_url: "https://docs.superdurable.io/agent-frameworks/sessions/"
source: "docs/content/agent-frameworks/sessions.mdx"
locale: "en"
---

> Index of every page for AI agents: https://docs.superdurable.io/llms.txt

# Sessions

A durable agent session is one Flow run that holds one conversation. Each model call and each tool call runs in a Step. So a crash, a deploy, or a long wait repeats nothing that already finished.

> **Diagram**: Your app's Client sends a message into the session Flow. Inside it, your framework's agent loop runs as Steps: a model call (RunModel), a tool call (CallTool), an approval (AwaitToolApproval), then the next model call. Dex records each Step's result before the turn moves on, and the Steps call your models and tools.

<a id="a-durable-agent-session"></a>

## A durable agent session

One Flow run is one agent session. The Flow ID is the session ID. Dex Agents builds the session Flow: the **dex-agents** package in Python and `@superdurable/dex-agents` in TypeScript. A framework adapter adds one agent framework to it.

The session stores the conversation in Attributes. A session waits for the next user message without using a Worker task slot.

Model calls run in a `RunModel` Step. In most harnesses, each `RunModel` Step makes one model call, and each tool call runs in its own Step. The Steps of one turn are:

| Step                    | What it does                                                                                                                      |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `RunModel`              | Makes one model call and records the response.                                                                                    |
| `CallTool`              | Runs one call of a read or an idempotent write. Dex may retry it.                                                                 |
| `CallSingleAttemptTool` | Runs one call of any other write. Dex runs it at most once.                                                                       |
| `AwaitToolApproval`     | Waits for a person to approve or reject a tool call. See [Approvals](https://docs.superdurable.io/agent-frameworks/approvals.md). |
| `ResumeTurn`            | Waits for every tool result of the model response, then moves back to `RunModel`.                                                 |

The tool calls of one model response run in parallel. When they all finish, `ResumeTurn` sends their results to the model.

<a id="latency-and-cost"></a>

### Latency and cost

Every session Step is SYNC: Dex commits the Step's start before the Worker gets it, and its result before the session moves on, each to object storage. A turn in which the model asks for three tools and then answers takes six Steps: two `RunModel`, three tool Steps, and one `ResumeTurn`. [Performance](https://docs.superdurable.io/intro/performance.md#latency-below-the-peak) measured a p50 of about 105 ms for a SYNC Step on a 2-vCPU server at half of its peak load. The three tool Steps run in parallel, so the turn waits on four Steps in a row. At that p50, they add about 0.4 seconds to the turn, on top of the model and tool time.

A `RunModel` Step retries up to three attempts within 30 minutes. A retry sends the model call to the provider again, so you pay for its tokens again. `run_model_limit` in Python, or `runModelLimit` in TypeScript, lowers the attempts for an expensive call. [Step timeouts](https://docs.superdurable.io/reference/agents/workers.md#timeouts) lists the defaults.

A crash repeats only the Step that was running. Dex does not replay the loop. So the agent code needs no determinism rules, and a code change takes effect at the next Step.

Two harnesses group more work into one Step:

- **Claude Agent SDK.** The Claude Code CLI runs a turn segment in one `RunModel` Step. The segment holds the model calls and the read tool calls, and a failed segment reruns as a whole. Writes leave the segment one at a time, each in its own Step, so they never run in parallel.
- **LangChain and LangGraph.** One `RunModel` Step runs the graph to its next tool calls. A graph can make several model calls on the way, and a retry repeats them together.

<a id="what-a-session-remembers"></a>

### What a session remembers

A session keeps one conversation: its messages, its tool calls, and their results. A new session starts empty. Dex Agents has no memory that one session shares with the next.

Keep long-term memory, such as a user's preferences or past orders, in a store that you own. That store can be your database or a Flow that you keep for each user. Give the agent a tool that reads it, and a tool that writes it with the right [policy](https://docs.superdurable.io/agent-frameworks/tool-calls.md#tool-policies-and-approvals).

A stopped session stays readable for the retention period, and then Dex deletes it. [History and retention](https://docs.superdurable.io/reference/agents/session-limits.md#history) has the defaults.

<a id="how-each-framework-runs-a-turn"></a>

<a id="features-by-harness"></a>

<a id="limits"></a>

<a id="framework-support"></a>

## Framework support

[Framework Support](https://docs.superdurable.io/agent-frameworks/framework-support.md) shows how your framework runs a turn, which session features it has, and its limits.

## Next

- [Tool Calls](https://docs.superdurable.io/agent-frameworks/tool-calls.md)
- [RPCs during a deploy](https://docs.superdurable.io/agent-frameworks/production.md#rpcs-during-a-deploy): what `send_user_message` does while no Worker runs
- [Agents reference](https://docs.superdurable.io/reference/agents.md)