> For the complete documentation index, see [llms.txt](https://dnotifier.gitbook.io/product-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/checkpoints.md).

# Checkpoints, sessions & resume

Keep agent and workflow runs **durable across turns and failures**. Pass a `sessionId` so the next run can continue the same conversation, retry from a failure, or replay a past attempt for testing.

{% hint style="info" %}
Available in the **JavaScript**, **Python**, and **Dart** SDKs.
{% endhint %}

## What you can build

| Use case                       | How                                                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| **Multi-turn assistant**       | Reuse the same `sessionId` so the agent remembers prior messages                                      |
| **Support ticket thread**      | One session per ticket; each reply is a new run under that session                                    |
| **Retry after a tool failure** | Call again with `mode: "retry"` (or `resume: true`) — finished work is kept, remaining tools continue |
| **Debug a bad run**            | `mode: "replay"` with an optional `fromCheckpointId` to re-run from a known point                     |
| **Long workflow continuity**   | Same `sessionId` on `runWorkflow` so `ctx.state` carries forward                                      |

## Core ideas

| Term           | Meaning                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| **Session**    | A durable thread (conversation, ticket, or job). Many runs can share one `sessionId`.                       |
| **Execution**  | One attempt of an agent or workflow. Retries and replays create a **new** execution under the same session. |
| **Checkpoint** | A saved snapshot of run state (messages, workflow state, progress). Used to continue or retry.              |

```
Session (ticket / conversation)
  ├── Execution 1  (first attempt — may fail mid-tools)
  ├── Execution 2  (retry — continues from checkpoint)
  └── Execution 3  (later user message — hydrates history)
```

{% hint style="info" %}
**Observability** (`observability: true` / `logs: true`) shows what happened in the dashboard. **Checkpoints** decide *how to continue*. You can use either or both.
{% endhint %}

## Who creates `sessionId`?

You can pass your own id, **or let the SDK create one** and read it from the run result.

| You do                                                            | What happens                                                                                                                                              |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pass `sessionId` / `session_id`                                   | That id is used for the run                                                                                                                               |
| Pass a checkpointer **without** a session id                      | SDK **creates** a session id and returns it as `result.sessionId`                                                                                         |
| Enable `observability` or `logs` without a session id             | SDK defaults checkpointer to `"remote"`, creates a session id, and returns `result.sessionId` (override with `checkpointer: "memory"` / custom / `false`) |
| Pass nothing (no session, no checkpointer, no observability/logs) | No session — one-off run                                                                                                                                  |

**Always save the returned id** if you want a follow-up turn:

```js
const turn1 = await notifier.runAgent(agent, {
  input: "Hi, my name is Sam.",
  checkpointer: "memory", // or omit and pass your own sessionId
});

const sessionId = turn1.sessionId; // SDK-created (or the one you passed)

const turn2 = await notifier.runAgent(agent, {
  input: "What is my name?",
  sessionId, // reuse — required for continuity
});
```

{% hint style="info" %}
If you already have a stable id (ticket number, chat id, user thread), pass that as `sessionId`. Otherwise omit it, enable a checkpointer (or pass nothing and use the minted id from observability), then **reuse `result.sessionId`** on the next call.
{% endhint %}

## Quick start — remember across turns

Reuse the **same** `sessionId` on every call. The SDK restores prior messages and appends the new user input.

{% tabs %}
{% tab title="JavaScript" %}

```js
// Option A — your id
const sessionId = "ticket-42";

// Option B — let the SDK create one on the first run
// const sessionId = (await notifier.runAgent(agent, { input: "...", checkpointer: "memory" })).sessionId;

const turn1 = await notifier.runAgent(agent, {
  input: "Hi, my name is Sam.",
  sessionId,
});

const turn2 = await notifier.runAgent(agent, {
  input: "What is my name?",
  sessionId: turn1.sessionId, // same session
});
// Agent can answer using history from turn1
```

{% endtab %}

{% tab title="Python" %}

```python
# Option A — your id
session_id = "ticket-42"

# Option B — let the SDK create one on the first run
# first = await notifier.run_agent(agent, input="...", checkpointer="memory")
# session_id = first["sessionId"]

turn1 = await notifier.run_agent(
    agent,
    input="Hi, my name is Sam.",
    session_id=session_id,
)

turn2 = await notifier.run_agent(
    agent,
    input="What is my name?",
    session_id=turn1["sessionId"],  # same session
)
```

{% endtab %}

{% tab title="Dart" %}

```dart
// Option A — your id
var sessionId = 'ticket-42';

// Option B — let the SDK create one on the first run
// final first = await notifier.runAgent(agent, input: '...', checkpointer: 'memory');
// sessionId = first['sessionId'] as String;

final turn1 = await notifier.runAgent(
  agent,
  input: 'Hi, my name is Sam.',
  sessionId: sessionId,
);

final turn2 = await notifier.runAgent(
  agent,
  input: 'What is my name?',
  sessionId: turn1['sessionId'] as String?, // same session
);
```

{% endtab %}
{% endtabs %}

When a session is active (passed or created), checkpoints are stored for that session when checkpointing is on. Omit `sessionId` and do not set a checkpointer if you want a one-off run with no memory.

## Resume, retry, replay

| Option             | Behavior                                                                         |
| ------------------ | -------------------------------------------------------------------------------- |
| `resume: true`     | Continue from the **latest** checkpoint in the session                           |
| `mode: "resume"`   | Same as resume                                                                   |
| `mode: "retry"`    | New execution from the failure (or a given checkpoint); keep completed tool work |
| `mode: "replay"`   | New execution that **re-runs** from a checkpoint (useful for testing)            |
| `fromCheckpointId` | Start from a specific checkpoint instead of the latest                           |

Every execution stores an **input** (including resume/retry/replay):

| Caller sent                   | Stored on the execution                                                                                                                 |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| A new message                 | That message (unchanged)                                                                                                                |
| No message (`null` / omitted) | A **marked copy** of the checkpoint’s input (or last user message): `{ continued: true, value, fromCheckpointId?, parentExecutionId? }` |

{% tabs %}
{% tab title="JavaScript" %}

```js
let result;
try {
  result = await notifier.runAgent(agent, {
    input: "Book a flight and email the itinerary.",
    sessionId,
  });
} catch (err) {
  // Tool failed mid-run — retry without losing earlier tool results
  result = await notifier.runAgent(agent, {
    input: "Book a flight and email the itinerary.",
    sessionId,
    mode: "retry",
  });
}
```

Or resume from a known checkpoint:

```js
await notifier.runAgent(agent, {
  sessionId,
  fromCheckpointId: "ckpt_...",
  mode: "replay",
});
```

{% endtab %}

{% tab title="Python" %}

```python
try:
    result = await notifier.run_agent(
        agent,
        input="Book a flight and email the itinerary.",
        session_id=session_id,
    )
except Exception:
    result = await notifier.run_agent(
        agent,
        input="Book a flight and email the itinerary.",
        session_id=session_id,
        mode="retry",
    )
```

{% endtab %}

{% tab title="Dart" %}

```dart
Map<String, dynamic> result;
try {
  result = await notifier.runAgent(
    agent,
    input: 'Book a flight and email the itinerary.',
    sessionId: sessionId,
  );
} catch (_) {
  result = await notifier.runAgent(
    agent,
    input: 'Book a flight and email the itinerary.',
    sessionId: sessionId,
    mode: 'retry',
  );
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
`resume` / `retry` / `replay` require a `sessionId` **or** a `fromCheckpointId`.
{% endhint %}

## Listen, MCP, and A2A

When an agent or workflow is **listening** (MCP server or A2A), remote invokes accept the same session / resume fields as `runAgent`:

| Field              | Purpose                                                              |
| ------------------ | -------------------------------------------------------------------- |
| `sessionId`        | Continue or checkpoint the same thread                               |
| `state`            | Workflow-style state object (merged over checkpoint state on resume) |
| `resume` / `mode`  | `resume`, `retry`, or `replay`                                       |
| `fromCheckpointId` | Resume from a specific checkpoint                                    |

Pass them on the invoke (MCP tool arguments / A2A message metadata that the gateway forwards into the remote-agent envelope). The host loads the checkpoint, merges any provided `state`, runs the agent, and returns `sessionId` / `checkpointId` / `mode` on the result when available.

```js
// Example remote invoke payload (gateway → listening host)
{
  agentName: "support",
  input: "Continue booking",
  sessionId: "sess_...",
  fromCheckpointId: "ckpt_...",
  mode: "resume",
  state: { locale: "en" },
}
```

→ [Serve agents over MCP](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/mcp-server.md) · [Agent-to-agent (A2A)](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/a2a.md)

## Workflows

Same options on `runWorkflow` / `run_workflow`. Reusing `sessionId` restores prior `ctx.state`. Resume/retry/replay follow the same rules as agents.

```js
const run = await notifier.runWorkflow({
  workflow,
  input: { orderId: "1001" },
  sessionId: "order-1001",
});

// Later / after a failure
await notifier.runWorkflow({
  workflow,
  input: { orderId: "1001" },
  sessionId: "order-1001",
  mode: "retry",
});
```

## Return values

Runs that use sessions/checkpoints typically include:

| Field          | Description                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------- |
| `sessionId`    | Thread id — **the one you passed, or the one the SDK created**. Save this for the next turn. |
| `executionId`  | This attempt (new on every run, including retries)                                           |
| `checkpointId` | Latest checkpoint written for this run (when checkpointing is on)                            |
| `mode`         | `run`, `resume`, `retry`, or `replay`                                                        |

```js
const { sessionId, executionId, checkpointId } = await notifier.runAgent(agent, {
  input: "Hello",
  checkpointer: "memory",
});
// Persist sessionId in your app (DB, cookie, ticket field) and pass it next time
```

## Checkpointer options

| Value                               | When to use                                      |
| ----------------------------------- | ------------------------------------------------ |
| *(omit)* + `sessionId`              | Default cloud storage for that session           |
| `"memory"` / in-memory checkpointer | Local tests or demos without persisting remotely |
| Custom `{ put, get, list }`         | Your own store (advanced)                        |
| `false`                             | Disable checkpointing even if `sessionId` is set |

{% hint style="info" %}
**Observability / logs:** defaults the checkpointer to `"remote"` (and mints a `sessionId` if needed) so the dashboard sessions list is populated. Override with `checkpointer: "memory"`, a custom store, or `false` to disable.
{% endhint %}

## Language guides

| Language                | Guide                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| JavaScript / TypeScript | [javascript-typescript.md](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/checkpoints/javascript-typescript.md) |
| Dart / Flutter          | [dart-flutter.md](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/checkpoints/dart-flutter.md)                   |
| Python                  | [python.md](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/checkpoints/python.md)                               |

## Related

* [Workflow observability](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/observability.md) — step timeline in the dashboard
* [Observability overview](https://dnotifier.gitbook.io/product-docs/observability/observability.md) — logs vs history vs observability
* [AI sessions](https://dnotifier.gitbook.io/product-docs/ai/sessions.md) — `sessionId` on `sendAI` for chat-style prompts
* [Define an agent](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/define-agent.md)
