---
title: "Agent Quick Start"
description: "Run your framework's agent as a durable Dex session from a downloaded example, approve a write, then stop the program while it waits and while a tool runs, and watch the session carry on."
canonical_url: "https://docs.superdurable.io/agent-frameworks/quick-start/"
source: "docs/content/agent-frameworks/quick-start.mdx"
locale: "en"
framework: "claude-agent-sdk"
language: "python"
---

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

# Agent Quick Start

This file shows the Claude Agent SDK version. Other frameworks: [Google ADK](https://docs.superdurable.io/agent-frameworks/quick-start.google-adk.md) · [LangChain and LangGraph](https://docs.superdurable.io/agent-frameworks/quick-start.langchain-langgraph.md) · [Mastra](https://docs.superdurable.io/agent-frameworks/quick-start.mastra.md) · [OpenAI Agents SDK](https://docs.superdurable.io/agent-frameworks/quick-start.openai-agents-sdk.md) · [Pydantic AI](https://docs.superdurable.io/agent-frameworks/quick-start.pydantic-ai.md) · [Vercel AI SDK](https://docs.superdurable.io/agent-frameworks/quick-start.vercel-ai-sdk.md)

Code on this page is in Python. Other languages: [TypeScript](https://docs.superdurable.io/agent-frameworks/quick-start.typescript.md)

Run your framework's agent as a durable Dex session, then stop it in the middle of a conversation and watch it carry on. It takes about 10 minutes.

> **Do it with a coding agent**
>
> Install Dex Skills once:
>
> Claude Code:
>
> ```bash
> claude plugin marketplace add superdurable/dex-skills
> claude plugin install superdurable-dex@superdurable
> ```
>
> Codex:
>
> ```bash
> codex plugin marketplace add superdurable/dex-skills
> codex plugin add superdurable-dex@superdurable
> ```
>
> Then paste this prompt:
>
> ```text
> Run the Dex Agent Quick Start in this folder.
>
> 1. Read https://docs.superdurable.io/agent-frameworks/quick-start.md and treat
>    it as the source of truth.
> 2. Ask which framework and language I want.
> 3. Start dexcli dev and run the example agent.
> 4. Approve the cancel_order call, stop the program while it waits, restart it,
>    and show me that the session carried on.
>
> Rules: stay inside this Quick Start. Do not invent APIs. Ask me before
> installing anything else.
> ```

<a id="before-you-start"></a>

<a id="what-you-will-build"></a>

<a id="run-it"></a>

<a id="start-in-an-empty-folder"></a>

<a id="get-the-example"></a>

## 1. Get the example and run it

In one terminal, run `dexcli dev` ([install `dexcli`](https://docs.superdurable.io/components/run-locally.md)). In a second terminal, download the example and ask the agent about an order:

**Python**

```bash
curl -sL https://codeload.github.com/superdurable/dex/tar.gz/main | tar -xz --strip-components=3 dex-main/examples/python/agent-harnesses
cd agent-harnesses
uv sync --locked
uv run --frozen python -m agent_harness_examples.quick_start claude-agent-sdk "Look up order 1001"
```

You need Python 3.11 or later with uv. It calls Claude, so set `ANTHROPIC_API_KEY` first.

It prints the session ID and the agent's reply:

```text
Session claude-agent-sdk-quick-start-<8 hex digits>
Agent: <the model's reply about order 1001>
```

Example: [examples/python/agent-harnesses/agent_harness_examples/quick_start/\_\_main\_\_.py](https://github.com/superdurable/dex/tree/main/examples/python/agent-harnesses/agent_harness_examples/quick_start/__main__.py)

The agent is a small order support agent with two tools. `look_up_order` reads an order, so Dex may retry it. `cancel_order` cancels an order that has not shipped; it is a write, so it runs at most once, and only after a person approves it.

<a id="approve-a-write"></a>

## 2. Approve a write

Run the same command with the message **Cancel order 1002**. The program stops and asks:

```text
cancel_order wants to run with {"order_id":"1002","reason":"requested by the customer"}. Approve? [y/N]
```

The session waits in `AwaitToolApproval`. Type **y**, and the agent cancels the order and replies. [Approvals](https://docs.superdurable.io/agent-frameworks/approvals.md) shows how your app reads and answers the waiting call, and how a person approves it in Dex Web.

<a id="stop-the-worker"></a>

## 3. Stop the program while the agent waits

Ask to cancel order 1002 again; each run without `--session-id` starts a new session. When the program asks you to approve, press Ctrl+C. The program, its Worker, and its Client stop, and the session keeps waiting in Dex.

Run the step 1 command again from the same folder, with `--session-id SESSION_ID` in place of the message. A new Worker starts, and the program asks about the same `cancel_order` call. Type **y**. The order is cancelled once, and the model calls before the restart stay done.

1. Worker: RunModel calls the model. The model asks to call cancel_order.
2. Dex Server: cancel_order waits in AwaitToolApproval. Dex Server holds the wait.
3. Worker: You stop the program, and its Worker stops.
4. Dex Server: The approval keeps waiting on Dex Server. No Worker is needed.
5. Worker, restarted: You start the program again. Its Worker connects to Dex.
6. Dex Server: You approve cancel_order at the program's prompt. Dex Server records the answer.
7. Worker, restarted: cancel_order runs once. The model writes the reply.
8. Dex Server: The turn completes.

The model call before the stop stayed done, and cancel_order ran once.

<a id="stop-while-a-tool-runs"></a>

## 4. Stop it while a tool runs

A crash in the middle of a tool call is the harder case. The example can slow each tool call down, so you have time to stop it.

1. Put `DEX_ORDER_DESK_TOOL_DELAY_SECONDS=20` in front of the step 1 command and ask about order 1001.
2. Within 20 seconds, kill the program as a crash would. A crash is a kill signal; Ctrl+C lets a running call finish first.

**Python**

```bash
pkill -9 -f agent_harness_examples.quick_start
```

Example: [examples/python/agent-harnesses/agent_harness_examples/quick_start/\_\_main\_\_.py](https://github.com/superdurable/dex/tree/main/examples/python/agent-harnesses/agent_harness_examples/quick_start/__main__.py)

3. Run the program again with `--session-id` and no message. The agent answers with the order.
4. Check how the tool call ran:

```bash
dexcli flow history --all SESSION_ID | jq '.events[]
  | select(.payload.context.stepType == "CallTool")
  | .payload.context | {finalAttempt, failure: .lastFailureInfo.details.detail}'
```

`finalAttempt` is **2**. The first attempt failed when the Worker disconnected, and because `look_up_order` is a read, Dex ran it again on the new Worker. The model call before it ran once.

Now do the same with a write: ask to cancel order 1002 with the delay set, approve it, kill the program within 20 seconds, and run it again with `--session-id`. Dex records `cancel_order` as `outcome_unknown` and runs it no second time, because it is a non-idempotent write. The agent tells the user that the outcome is unknown, and your application checks the order system before anyone tries again. [Reconcile outcome_unknown](https://docs.superdurable.io/agent-frameworks/tool-calls.md#reconcile-outcome-unknown) shows how.

<a id="make-it-durable"></a>

## What made it durable

The example writes the agent as your framework alone would, then wraps it in a Dex agent session and gives each tool a policy. [What changes in your code](https://docs.superdurable.io/agent-frameworks/add-to-your-agent.md#what-changes-in-your-code) shows both versions for every framework.

<a id="use-it-in-your-own-agent"></a>

<a id="complete-files"></a>

<a id="wire-it-into-your-app"></a>

<a id="web-handler"></a>

## Next

- [Add Dex to Your Agent](https://docs.superdurable.io/agent-frameworks/add-to-your-agent.md) moves this agent into your own app, with the complete files and a web app.
- [Sessions](https://docs.superdurable.io/agent-frameworks/sessions.md) explains what survived the restart, and how your framework's turn maps onto Steps.
- [Tool Calls](https://docs.superdurable.io/agent-frameworks/tool-calls.md) explains why `cancel_order` runs at most once, and the one narrow case where a write can run twice.
- [Built-in Agent Loop](https://docs.superdurable.io/agent-frameworks/built-in-agent-loop.md) builds an agent without a framework.
- [Order Support Agent](https://docs.superdurable.io/use-cases/order-support-agent.md) is the full example, with its HTTP routes.