Long-Running AI Agents for Beginners: The Playbook on Saving Progress and Resuming

Meera, a developer in Pune, built a small AI agent that reads a customer’s refund request, checks the order, writes to the warehouse and sends a confirmation email. On her laptop it finished in a minute. Then her manager said, “Great. Now let it process 2,000 refunds overnight.”

At 3 a.m. the server restarted for an update. The agent was on refund number 1,140. In the morning Meera found it had started again from refund number 1. Some customers got two emails. This is the problem of long running AI agents: the longer a job runs, the more likely something interrupts it.

Last verified: 4 November 2026. AI tools change fast; check the linked sources for anything newer.

Who this is for: beginners who have built or read about a simple AI agent and now want it to run for minutes, hours or days without breaking. Time needed: about 30-45 minutes.

What is a long-running agent, in simple words

An AI agent is a program that uses a language model to decide which step to take next, call tools, and repeat until the job is done. If you are new to this, read our AI agents playbook first.

A long-running agent is simply an agent whose job takes a long time: many steps, slow tools, or waiting for a person to say yes. Think of a cook making a slow stew versus a quick sandwich. The sandwich can start over if you drop it. The stew cannot.

Microsoft’s documentation describes three reasons these agents are hard: the sessions can last hours, days or weeks and collect a lot of state; model calls cost tokens, so a restart wastes money; and servers restart, deploy or crash. Their answer is “durable execution”: save progress at every step and resume from it.

The everyday analogy is a video game. A game without save points makes you restart from level one after every crash. A checkpoint is a save point for your agent.

The playbook at a glance

1. Break the job into small steps with a clear order.
2. Save progress after every step.
3. Make every step safe to repeat.
4. Retry the right failures and wait for people properly.
5. Watch the run and test a crash on purpose.

Play 1: Break the job into small steps

Goal: give the agent places where it can be saved and resumed.

1. Write the job as a list of steps, for example: read request, check order, write to warehouse, send email.
2. Give every job a stable run ID, such as refund-1140, so you can find it again.
3. Keep each step small enough that repeating it is cheap.

Meera stops treating “process 2,000 refunds” as one big job. It becomes 2,000 small jobs, each with four steps and its own ID.

You are done when: you can point at any refund and say which step it is on.

Play 2: Save progress after every step

Goal: never lose finished work.

1. Choose storage that survives a restart: a database, not a variable in memory.
2. After each step, save the run ID, the step name, the result and the conversation so far.
3. On start, look up the run ID. If it exists, skip every step already saved.

Here is the idea in a few lines. It is an illustration, not code for one specific tool:

for step in steps:
    saved = db.get(run_id, step.name)
    if saved:                  # finished before the crash
        result = saved
    else:
        result = step.run(result)
        db.save(run_id, step.name, result)
return result

In plain words: before doing a step, ask “did I already do this?”. If yes, reuse the saved answer. If no, do it and write it down. Sources I read suggest a real database such as PostgreSQL for production and a simple file or SQLite only for learning on your own laptop.

Meera adds a small table. After the 3 a.m. restart, her agent would now skip the 1,139 finished refunds.

You are done when: you can stop the program mid-run, start it again, and it continues instead of restarting.

Play 3: Make every step safe to repeat

Goal: a repeated step must not cause a second email or a second payment.

This is the part beginners miss. A crash can happen after the email was sent but before you saved “email sent”. On restart the agent sends it again. Restate’s engineering blog makes this point: a checkpoint does not record which side effects already happened, so a restart can repeat all of them.

1. List the steps that change the outside world: emails, payments, database writes.
2. Give each one an idempotency key, a unique label like refund-1140-email. “Idempotent” just means doing it twice has the same effect as doing it once.
3. Before acting, check whether that key was already used. If yes, skip.

Meera gives the confirmation email the key refund-1140-email. The mail step now refuses to send it twice.

You are done when: you can run any step twice on purpose and nothing doubles.

Play 4: Retry the right failures and wait for people properly

Goal: handle small failures quietly and long waits cheaply.

1. Retry temporary problems, such as a model rate limit or a slow network, a few times with a growing pause between tries.
2. Do not retry forever. After a limit, mark the run as “needs a person” and stop.
3. For approvals, save the state, end the process, and wake the run when the answer arrives. Do not keep a program running just to wait.

Meera decides refunds above a limit need her manager’s approval. The agent saves its state, sends a message and goes to sleep. Two days later the approval arrives and the run wakes up exactly where it stopped. Read our guardrails and human approval playbook for how to design that approval step.

You are done when: a temporary error fixes itself, and a two-day wait costs nothing while it waits.

Play 5: Watch the run and test a crash on purpose

Goal: trust the system before a real night shift.

1. Log the run ID, step name and status for every step. Our observability playbook shows how.
2. Add a test that kills the program halfway and checks that the restart finishes the job without duplicates. See the evals playbook for test ideas.
3. Be careful when you change the code while runs are paused. Old runs may meet new rules, so note a version number on each run.

Meera unplugs her test server during run 50 of 100. When it restarts, runs 51 to 100 finish and nobody gets a second email.

You are done when: a deliberate crash leaves you with a finished job and no duplicates.

Do you need a framework or just a database table?

The sources I read describe durable execution as logging each step so a restart replays saved results and continues from the step that failed. Start with your own table to learn the idea, then move to a tool when the job grows.

Mistakes to avoid

• Keeping progress in memory. A restart erases it. Save to a database.
• Saving only at the end. One crash loses everything. Save after every step.
• Ignoring repeated side effects. Use idempotency keys for emails and payments.
• Retrying forever. Set a limit and hand the run to a person.
• Never testing a crash. Kill the program on purpose before it happens at 3 a.m.

How to know it is working

• After a restart, the count of finished steps does not go back to zero.
• Customers never report a duplicate email or charge.
• Your logs show waiting runs using no running program.
• Token cost for a crashed-and-resumed run is close to a normal run (illustrative goal).

Your checklist

• ☐ The job is split into small named steps
• ☐ Every run has a stable run ID
• ☐ Progress is saved to a database after each step
• ☐ Emails and payments use idempotency keys
• ☐ Retries have a limit and a pause
• ☐ A crash test passes

Frequently asked questions

What is checkpointing in an AI agent?

It means saving the agent’s progress, such as the conversation and the results of finished steps, to storage after key steps. If the program stops, it can load the save and continue.

Is checkpointing the same as durable execution?

Not quite. Checkpointing saves at set points. Durable execution also records each step and handles retries and waiting, so recovery is automatic. Some vendors argue plain checkpointing is not enough for production.

How long can an agent run?

With saved state and a way to wake it up, an agent can wait hours or days. Microsoft’s documentation describes sessions lasting hours, days or weeks for human-in-the-loop work.

Do I need a special framework?

No, not to begin. A database table and idempotency keys teach you the ideas. Move to a durable tool when jobs get long or numerous.

Meera’s next night shift

The next time the server restarted at 3 a.m., Meera slept through it. The agent woke up, found refund 1,140 in its table, and carried on. Nobody got a second email.

Your next action: take one agent you have and add a run ID and a step table today. Then try the crash test from Play 5.

Sources: Durable Task for AI Agents (Microsoft Learn), Agent checkpointing is far from production-grade resiliency (Restate), How to Checkpoint and Resume AI Agent Execution (Fast.io). The story, names and numbers about Meera are illustrative.