Agents from scratch (TypeScript) · Chapter 8 of 18

Planning

By the end of this chapter you can ask a model for a plan instead of a next step: the calls it would make, in order, with placeholders for what the lookups will find. You can describe that plan once with zod, check it, show it to a person, execute it without the model, and deal with a step that fails. 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

The loop from chapter 3 decides one step at a time. That is its strength, and Meenakshi's problem with it: nobody knows what the agent will do until it has done it. When a customer on WhatsApp asks "what happens now?", or when her team wants to look over a refund before it goes through, "wait and see" is not an answer.

Anjali asked the question differently: could the agent say what it is going to do, before doing it? It can. You ask the model for a plan: the whole list of calls, written out in advance. A plan can be read, checked, approved, logged and replayed. It is also cheaper: one request to plan, then the steps run with no model at all. The price is that a plan is made at one moment, and the world keeps moving.

What you build: 4 tasks

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

  1. Task 1

    plan.ts: ask for a plan

    Export two zod schemas from plan.ts: Step, with tool (one of GharFix's tool names, the keys of FUNCTIONS) and arguments (an object with any keys and values), and Plan, with steps (an array of Step); and export the type Plan, inferred from the schema. Then export async function getPlan(request): one request to lab-chat with a system message (GharFix's booking assistant, saying today is 2026-10-22, asking it to plan the tool calls), the request as the user's message, GharFix's tools, tool_choice set to 'none', and a response format of type json_schema, named plan, whose schema is Plan's JSON Schema. Return the reply parsed by Plan.

    The check calls getPlan with Meenakshi's job J14 and compares the plan with the model's reply, and gives Plan a step whose tool GharFix does not have.

  2. Task 2

    show-plan.ts: the plan for Meenakshi

    Get a plan with your getPlan (import it from ./plan.ts) for this request, exactly:

    Book an electrician in Whitefield tomorrow: a switch board is sparking. I am Kiran Hegde, phone 9741234567.

    Print it for Meenakshi before anything runs: first Plan for N steps: with the number of steps; then one line per step, numbered from 1: the number, a full stop and a space, the tool's name, and in brackets its arguments as key=value, in the plan's order, with a comma and a space between them. For another request, a line was:

    1. find_technicians(service=plumbing, area=Koramangala, date=2026-10-23, slot=morning)

    Last, print Changes data: followed by the names of the steps that are not lookups (a lookup's name starts with find_, check_ or get_), with a comma and a space between them, or nothing if there are none.

  3. Task 3

    run-plan.ts: execute a plan

    Export function execute(plan) from run-plan.ts. It runs the plan's steps in order with GharFix's functions (FUNCTIONS) and returns the array of their results.

    Before a step runs, fill its placeholders: an argument whose value is a placeholder like <technician_id from find_technicians> takes that key from the result of the step that ran that tool; when that result is an array, from its first row.

    Stop at the first step whose result is an error (keep that result as the array's last). When a placeholder cannot be filled (the tool found nobody, or its result has no such key), add an error result, an object with an error key, and stop there too: a step that cannot be filled must never run.

    The check executes plans for a booking with no slot, for a service nobody offers in that area, and for a reschedule GharFix refuses.

  4. Task 4 · interview question

    Interview: replan.ts, a plan that went stale

    replan.ts plans two customers' bookings, runs each plan's lookups so Meenakshi can read who will come, and then books them one after the other. Both plans chose the same technician for the same slot, so the second booking fails, and the program reports undefined for that customer.

    Fix bookAll(requests) so that when a customer's booking fails, their request is planned again from the start (a new plan, with fresh lookups) and that plan is run. bookAll returns an object from each customer's name to their booking ID, or, if they still cannot be booked, to the error's text.

    The check calls bookAll with the two customers, and with three customers who all want the same slot.

What you will learn

  • A planning request: tools offered, none called, a JSON plan back.
  • Placeholders: how a plan refers to what a lookup will find.
  • A plan as data: one zod schema for the request, the check and the type.
  • Executing a plan, step by step, without the model.
  • When a step fails: what the plan cannot know.

More in Agents that hold up

Build "Planning" 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.