Agents from scratch · Chapter 9 of 18

Run state

By the end of this chapter you can treat an agent's run as data: a Pydantic model holding its conversation, its results and its status, saved to a file after every step, and loaded again to go on from where it stopped, without doing anything twice. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Agents that hold up
  • 4 tasks
  • Python
  • In the all labs plan

The first 2 chapters of Agents from scratch are free. This one comes with the all labs plan.

Why you need this

So far a run has lived in a few local variables: messages, a counter, the results. When the program ends, the run is gone. That was fine in a terminal. It is not fine for GharFix, where the agent runs on a server that is redeployed twice a day, where a request to the model can hang until it times out, and where (from chapter 10) a run will wait an hour for a customer to say yes.

Meenakshi brought the case that made Vikram write this chapter. A customer wrote at 9:58 that a repair had not lasted. At 9:59 the server restarted, mid-run, and the customer heard nothing. Someone ran the request again from the top. Here is what GharFix's request_refund does when it is called twice for the same booking:

>>> gharfix.request_refund("GF442328", "the fan still makes a noise")
{'booking_id': 'GF442328', 'decision': 'revisit', 'revisit': 'a technician comes back for free within 48 hours', 'policy': '5.2'}
>>> gharfix.request_refund("GF442328", "the fan still makes a noise")
{'booking_id': 'GF442328', 'decision': 'refund', 'refund': 349, 'status': 'refunded', 'policy': '5.3'}

The first run had already asked for the free revisit (policy 5.2). The second call is policy 5.3: a refund, paid out, for a repair nobody had gone back to look at. Farooq found it in the ledger. Running a call twice is not "trying again" when the call changes the world.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    run_state.py: a run as data

    Write a Pydantic model RunState in run_state.py, with these fields: run_id (text); question (text); status, one of running, waiting, done or failed, running at first; messages, a list of dictionaries; results, a dictionary from a tool call's id to its result as JSON text, empty at first; steps, the number of requests sent, 0 at first; and answer, text or None, None at first.

    Then three functions: new_run(question) returns a new RunState with a new random run_id and two messages, a system message (GharFix's booking assistant, saying today is 2026-10-22) and the question as the user's message; save(state, path) writes the state to that file as JSON; load(path) reads it back as a RunState.

  2. Task 2

    saved_run.py: save after every step

    Write run(question, path, max_steps=10) in saved_run.py. It starts a run with new_run (import it, save and load from run_state.py), saves it, and runs chapter 3's loop on the state's messages with lab-chat and GharFix's tools: after every request, add 1 to steps and append the model's message to messages as a dictionary; run every call with GharFix's function, record its result (JSON text) in results under the call's id, and append the tool message; then save the state to path, before the next request.

    When the model answers, set status to done and answer to its text, save, and return the state. If max_steps requests have been sent and the last still asked for tools, set status to failed, save and return it.

    The check runs a booking, then runs one again with a server that dies as book_slot is about to run, and reads what was saved.

  3. Task 3

    resume.py: go on from the file

    Write resume(path, max_steps=10) in resume.py. It loads a saved run and goes on from where it stopped, without repeating anything already done, and returns the state. A run whose status is done or failed is returned as it is, with no request.

    If the last message is the model's, with tool calls that have no tool messages after them, first give each call its tool message: the result recorded in results under its id, if there is one (that call already ran: never run it again), or else run it now and record it. Then go on with task 2's loop: steps keeps counting from the saved number, the state is saved after every step, and the run ends done with its answer, or failed after max_steps requests in all.

    The check writes run files that stopped in different places, one of them just after a booking was made but before its tool message was saved.

  4. Task 4 · interview question

    Interview: fix_resume.py, a resumed run that books twice

    fix_resume.py saves its runs so they can be resumed. Meenakshi cut the power just after a booking was made, while the model was writing its answer, and resumed: the customer now has two bookings, with two plumbers.

    Fix run(question, path) and resume(path) so that a run cut off at any request can be resumed, and the resumed run goes on from where it stopped: it never repeats a call the first run made, and it ends with one booking and the model's answer.

    Keep the names client, RunState, run, resume and save, and the power-cut test at the bottom. The check cuts the power at different requests and counts the bookings.

What you will learn

  • A run as data: one Pydantic model for everything a run knows.
  • Saving after every step, and what a crash can still lose.
  • Resuming from a file, from exactly where the run stopped.
  • Never repeating a call that already ran: results by call id.

More in Agents that hold up

Build "Run state" yourself

GharFix, a Bengaluru home-services company, needs an assistant that books, reschedules and refunds safely. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Agents from scratch are free. This one comes with the all labs plan.