AI ordering agent project · 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), read its reply into a Pydantic class, and check every argument the model writes for a tool before the tool runs, with 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
- Python
- In the all labs plan
The first 2 chapters of AI ordering agent project are free. This one comes with the all labs plan.
Why you need this
Of the 19 pilot orders that went wrong, most were words read into the wrong fields: the 1 pm slot instead of 12:30, Wednesday instead of Tuesday, a Jain member down as veg. Bhavna checks every order by hand against the WhatsApp message. For launch week she wants the agent to show what it understood as fields she can compare (zone, date, time, dish, quantity, diet), not a paragraph.
There is a second place where the model writes data for your code: the arguments of every tool call. Since chapter 3 run_tool does json.loads on them and calls the tool. Kunal ran the tools with arguments a model could write, unchecked, and this is what happened:
find_slots({"zone_name": "Thane", "date": "2026-11-03"})
-> TypeError: find_slots() got an unexpected keyword argument 'zone_name'
find_slots({"zone": "Thane", "date": "2026-02-30"})
-> ApiError 422 validation_failed The request is not valid
...
find_slots({"zone": "Thane", "date": "2026-11-03", "time": "12:15"})
-> []
place_order({"slot_id": 80, "dish_id": 25, "quantity": "two"})
-> ApiError 422 validation_failed The request is not valid
...
find_dish({"zone": "Thane", "dish_name": "Jain Thali")
-> JSONDecodeError: Expecting ',' delimiter: line 1 column 44 (char 43)
A crash, two refusals that do not say what is wrong, and an empty list that looks like "no slots" when the truth is "no slot starts at 12:15". 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.py: what the member asked for, as data
In agent/understand.py, write response_format(): {"type": "json_schema", "json_schema": {"name": "order_request", "strict": True, "schema": OrderRequest.model_json_schema()}}.
Then understand(message): one request with client.chat.completions.create, model agent_settings.model, temperature 0, response_format=response_format(), and the messages system_prompt(agent_settings.today_date(), ["Read the member's message and fill in what they ask for."]) and {"role": "user", "content": message}. Return OrderRequest.model_validate_json(the reply's content); when that raises a pydantic ValidationError, raise NotUnderstood with a sentence instead.
The Check compares your response format with the schema, sends "Book 2 Jain Thali for Tuesday lunch at 12:30 in Thane" through understand and reads what the lab model received and what you returned (Thane, 2026-11-03, 12:30, Jain Thali, 2, jain), then uses lab-chat-sloppy, whose reply is not plain JSON, and wants NotUnderstood. Then POST /agent/understand as Tara.
- Task 2
args.py: each tool's arguments as a Pydantic model
In agent/tools/args.py, write the fields of the five models (each inherits from Args, which forbids extra keys). FindDishArgs: zone (Zone), dish_name (str or None, default None, 1 to 60 characters), diet (Literal["veg", "jain", "non-veg"] or None, default None). FindSlotsArgs: zone (Zone), date (the type date), time (Literal["12:00", "12:30", "13:00"] or None, default None). PlaceOrderArgs: slot_id and dish_id (int, more than 0), quantity (int, 1 to 10). ListMyOrdersArgs: no fields. PayOrderArgs: order_id (int, more than 0).
The Check validates good arguments with each model (all must pass) and fourteen bad ones (all must be refused): Powai, a missing zone, an empty dish_name, the diet vegan, an extra kitchen_id, 30 February, the date tomorrow, a time of 12:15, quantities of 0 and 11, a slot_id of 0, a missing dish_id, an order_id of -2 and a user_id given to list_my_orders. FindSlotsArgs must give back a real date.
- Task 3 · interview question
Interview: args.py, check the model's arguments
In agent/tools/args.py, write parse_args(name, arguments): the checked arguments as a dict ready for the tool, model.model_dump(mode="json") (a date comes back as "2026-11-03"), where model is ARGS[name]. Raise BadArguments with a sentence the model can act on when there is no model for the name (say the name), when the text is not valid JSON or not a JSON object, and when Pydantic refuses it: one sentence that names the tool and lists each problem as "<field>: <message>", joined with "; ". Empty text means no arguments, {}.
The Check parses good arguments for find_slots (every field, the date as text) and list_my_orders, then wants BadArguments for book_dabba (its name in the sentence), broken JSON, a JSON list and place_order with a quantity of 0 and an extra user_id (a sentence naming place_order, quantity and user_id, without pydantic's links). Then the given run_tool with zone_name instead of zone must raise your BadArguments.
Kunal will ask: the tool's JSON schema already told the model the types. Why check the arguments again in Python?
What you will learn
- Text out: why a reply's content is text, even when it looks like JSON.
- Structured outputs: response_format with a json_schema, and what strict demands of the schema.
- Pydantic as the reader: model_validate_json, and its ValidationError when the reply does not fit.
- What a tool's JSON schema does not do: it is advice the model reads; nothing enforces it.
- Pydantic models for arguments: Literal, Field limits, optional fields, real dates, extra keys refused.
- Errors written for the model: errors(include_url=False), joined into one sentence.
More in When things go wrong
Build "Structured outputs and checked arguments" yourself
DabbaDrop members want to order by chat. You build the agent that books their tiffins through DabbaDrop'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 ordering agent project are free. This one comes with the all labs plan.