AI booking agent project (TypeScript) · Chapter 4 of 12
Structured outputs and checked arguments
By the end of this chapter you can ask the model for data instead of prose, with a JSON schema in the request (a structured output), check its reply with zod, and check every argument the model writes for a tool before the tool runs: with zod's strict(), extend() and superRefine(), and a sentence the model can act on when something is wrong. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: When things go wrong
- 3 tasks
- TypeScript
- In the all labs plan
The first 2 chapters of AI booking agent project (TypeScript) are free. This one comes with the all labs plan.
Why you need this
Of the 286 WhatsApp bookings Datta's box office typed in during the trial weekend, 17 went wrong, and most of them were words read into the wrong place: the 6:15 pm show instead of 6:45, a balcony seat for a member who had said "under ₹200". Datta checked every booking by hand against the message. Sayali wants the site's chat to show the member what the agent understood, as fields they can check at a glance (the show, the day, the part of the day, how many seats, the most a seat may cost, aisle or centre), before anything is booked. A paragraph of prose cannot be compared field by field. Data can.
There is a second place where the model writes data for your code: the arguments of every tool call. Since chapter 3, runTool does JSON.parse on them and calls the tool. Nikhil called the tools with arguments a model could write, unchecked, exactly as chapter 3's runTool would:
find_showtimes({"date_name":"2026-11-07","title":"Ghar Wapsi Express"})
-> 3 rows, the first: {"showtime_id":2,"starts_at":"Fri 6 Nov, 12:15 pm","venue":"Kala Talkies","prices":"Front ₹120, Middle ₹180, Balcony ₹240","name":"Ghar Wapsi Express"}
find_showtimes({"date":"2026-02-30","title":"Ghar Wapsi Express"})
-> ApiError 422 validation_failed Some fields are not right
find_showtimes({"date":"2026-11-07","title":"Ghar Wapsi Express","part_of_day":"dawn"})
-> []
book_seats({"showtime_id":18,"count":0})
-> TypeError Cannot read properties of undefined (reading 'label')
book_seats({"showtime_id":"18","count":"two"})
-> ApiError 409 no_seats There are no two free seats side by side for showtime 18
find_showtimes({"date":"2026-11-07","title":"Ghar Wapsi Express",})
-> SyntaxError Expected double-quoted property name in JSON at position 50 (line 1 column 51)
Read the first one again. A misspelt key means no date at all, the API lists every day, and the first row is Friday's 12:15 pm show: the wrong show, offered with confidence. Then a refusal that does not say which field is wrong, an empty list that looks like "nothing is on", a crash deep in the seat picker, and a crash in JSON.parse. The model cannot fix what nobody tells it.
What you build: 3 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
understand.ts: what the member asked for, as data
In src/agent/understand.ts, write responseFormat(): { type: 'json_schema', json_schema: { name: 'booking_request', strict: true, schema: z.toJSONSchema(BookingRequest) without its $schema key } }.
Then understand(message): one request with client.chat.completions.create, model agentConfig.model, temperature 0, response_format responseFormat(), and the messages systemPrompt(today(), ["Read the member's message and fill in what they ask for."]) and { role: 'user', content: message }. Parse the reply's content as JSON, check it with BookingRequest.safeParse and return the data; when the text is not JSON or the check fails, throw a NotUnderstood with a sentence of yours.
The Check compares your response format with the schema, sends "Book two seats for Ghar Wapsi Express on Saturday evening, near the aisle, under ₹200 each" through understand and reads what the lab model received and what you returned (Ghar Wapsi Express, 2026-11-07, evening, 2, 200, aisle), then uses lab-chat-sloppy, whose reply is not plain JSON, and wants a NotUnderstood. Then POST /agent/understand as Neha.
- Task 2
args.ts: the arguments' rules, in code
In src/agent/tools/args.ts, write onSaleDay: z.iso.date('date must be a real day, written YYYY-MM-DD') with a superRefine that adds a custom issue '<day> is in the past: today is <first>' before first = today(), and '<day> is not on sale yet: Parda sells seats up to <last>' after last = addDays(first, DAYS_ON_SALE).
Then ARGS, one checker per tool, each specs.ts's zod object made .strict(), extended first where a rule is stricter: find_shows (title and language: words), find_showtimes (date: onSaleDay, title: words), book_seats (showtime_id: id, max_price: id.optional()), list_my_bookings (only strict), pay_booking (booking_id: id).
The Check passes good arguments to each checker (all must pass, today and the last day on sale too) and sixteen bad ones (all must be refused): 2026-02-30, the word tomorrow, a day in the past, a day after 5 December, an extra venue, the part of the day dawn, an empty title, a count of 0 and of 7, a showtime_id of 0, a max_price of 0, the seating window, a missing count, a seat_ids nobody asked for, a booking_id of -2, and a user_id given to list_my_bookings.
- Task 3 · interview question
Interview: args.ts, check the model's arguments
In src/agent/tools/args.ts, write parseArgs(name, text): the checked arguments as an object ready for the tool. Throw BadArguments with a sentence the model can act on when ARGS has no checker for the name ('There is no tool called <name>'), when the text is not JSON or not a JSON object, and when the checker refuses it: 'The arguments for <name> are not right: ' then each issue as '<path>: <message>', joined with '; ' (the path 'arguments' when it is empty). Empty text means no arguments, {}.
The Check parses good arguments for find_showtimes and list_my_bookings, then wants BadArguments for book_tickets (its name in the sentence), broken JSON, a JSON list and book_seats with a count of 0 and an extra user_id (one sentence naming book_seats, count and user_id). Then the given runTool with date_name instead of date must throw your BadArguments.
Nikhil will ask: the tool's JSON schema already told the model the types. Why check the arguments again in code?
What you will learn
- A reply is text: why content is a string, even when it looks like JSON.
- Structured outputs: response_format with a json_schema, and what strict demands of the schema.
- zod reads the reply: JSON.parse, then safeParse, and one error of your own when either fails.
- What a tool's schema does not do: the model reads it as advice; nothing enforces it.
- zod's strict(), extend() and superRefine(): unknown keys refused, stricter rules, rules no JSON schema can carry.
- Errors written for the model: zod's issues joined into one sentence.
More in When things go wrong
Build "Structured outputs and checked arguments" yourself
Parda members want to book by chat. You build the agent that finds the show, holds the seats through Parda's own API, and asks before it pays. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of AI booking agent project (TypeScript) are free. This one comes with the all labs plan.