Agents from scratch (TypeScript) · Chapter 9 of 18

Run state

By the end of this chapter you can treat an agent's run as data: one zod schema holding its conversation, its results and its status, saved to a file after every step, parsed again when it is loaded, and resumed 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
  • TypeScript
  • In the all labs plan

The first 2 chapters of Agents from scratch (TypeScript) 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 requestRefund does when it is called twice for the same booking:

requestRefund({ booking_id: 'GF442328', reason: 'the fan still makes a noise' });
requestRefund({ booking_id: 'GF442328', reason: 'the fan still makes a noise' });
{ booking_id: 'GF442328', decision: 'revisit',
  revisit: 'a technician comes back for free within 48 hours', policy: '5.2' }
{ 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.ts: a run as data

    Export a zod schema RunState from run-state.ts, and the type RunState inferred from it, with these fields: run_id (text); question (text); status, one of running, waiting, done or failed, running by default; messages, an array of messages that each have a role, typed as the SDK's ChatCompletionMessageParam; results, an object from a tool call's id to its result as JSON text, empty by default; steps, the number of requests sent, 0 by default; and answer, text or null, null by default.

    Then export three functions: newRun(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, parsed by RunState, so a damaged file (a status that is not one of the four, a message with no role) fails to load.

  2. Task 2

    saved-run.ts: save after every step

    Export async function run(question, path, maxSteps = 10) from saved-run.ts. It starts a run with newRun (import it, save and load from ./run-state.ts), 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 push the model's message onto messages; run every call with GharFix's function from FUNCTIONS, record its result (JSON text) in results under the call's id, and push 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 maxSteps 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 in a program that dies as book_slot is about to run, and reads what was saved.

  3. Task 3

    resume.ts: go on from the file

    Export async function resume(path, maxSteps = 10) from resume.ts. 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 maxSteps 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.ts, a resumed run that books twice

    fix-resume.ts 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 exported 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 zod schema for everything a run knows.
  • Saving after every step, and what a crash can still lose.
  • Loading is parsing: a saved file is untrusted until the schema says so.
  • 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. You build it in TypeScript. 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 (TypeScript) are free. This one comes with the all labs plan.