AI ordering agent project · Chapter 1 of 12

What an agent is

By the end of this chapter you can send a conversation to a chat model with the openai package, read what comes back (words, or a request to run a tool), say what a tool call is and what it is not, and explain why a model that says "Done! Your dabba is booked" has booked nothing. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The loop
  • 3 tasks
  • Python
  • Free chapter

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.

Why you need this

DabbaDrop's ordering API works: kitchens, slots, holds, orders, payments, all built in Project: DabbaDrop's ordering backend. But members still order on WhatsApp. In the pilot week Bhavna's operations team typed 312 WhatsApp orders into the API by hand, and 19 of them went wrong: a Jain member got onion, an order went in for the wrong day, the 1 pm slot instead of 12:30, and a payment was taken twice when someone pressed Pay again.

Farah, the founder, wants members to order in their own words, in the app's chat, from launch week (Monday 2 November 2026). Tara writes "Book 2 Jain Thali for Tuesday lunch at 12:30 in Thane", and something reads it, finds the slot and the dish with the real API, places the order, and asks before it takes money. Kunal, DabbaDrop's senior developer, builds it with you.

The API cannot do this alone. It wants {"slot_id": 80, "items": [{"dish_id": 25, "quantity": 2}]}. Tara does not know that slot 80 is Tuesday 12:30 in Thane, or that dish 25 is the Jain Thali. Something has to turn her words into the right calls. That something is an agent.

The lesson

The plan: a loop of model, tools, results

An agent is a loop. Your code sends the model the conversation and a list of tools it may ask for. The model answers in one of two ways: in words, or with a request ("call find_slots with zone Thane, date 2026-11-03"). Your code runs that tool, adds its result to the conversation, and asks again. When the model answers in words, the loop ends. The model never runs anything itself.

Over 12 chapters you build DabbaDrop's ordering agent: one request and one reply (1), the tools (2), the loop (3), checked arguments (4), errors as results (5), conversations kept in Postgres (6), a yes from the member before any payment (7), remembered preferences (8), a trace Bhavna can read (9), safety against instructions hidden in data (10), evals (11), and budgets and streaming (12).

Tour of the codebase

Everything is new. The ordering backend is given whole, and the agent lives beside it:

app/ alembic/ scripts/   the ordering API: the backend project's take-home
agent/__main__.py        python -m agent: migrations, the seed, the server
agent/main.py            create_app(): the ordering API plus /agent/...
agent/config.py          agent_settings: the model, the API's URL, today
agent/prompt.py          system_prompt(today): the first message
agent/routes.py          POST /agent/first-step
agent/deps.py            get_api: the API as the signed-in member
agent/dabba_api.py       DabbaApi (get, post, delete), ApiError
agent/testing.py         the app in memory, for tests and checks
agent/tools/specs.py     one tool, find_slots, as the model sees it
agent/llm.py             yours: chat (Task 1)
agent/reply.py           yours: read_reply (Task 2), what_it_wants (Task 3)

Start it in the terminal. The terminal is the server's log: one JSON line per request.

$ python -m agent
...
Migrations: up to date
...
INFO:     Uvicorn running on http://127.0.0.1:8101 (Press CTRL+C to quit)
...
INFO:     Application startup complete.
{"id": "e991aa9999e1424f9b8e8c3d27011f3b", "method": "POST", "path": "/agent/first-step", "status": 200, "ms": 929.8, "user_id": 2}

(This run was on port 8101; yours is on 8000.)

Send "Is the app up?" from the request pane: 200. With the starter, "Ask the model, with find_slots" answers 500, and the log ends with NotImplementedError: Task 1: chat is not written yet.

Mounted, but over HTTP

agent/main.py takes the ordering API's own create_app() and adds the agent's routes under /agent. One process, one port (the request pane has one), one login (the agent's routes use the API's current_user), one database.

But the agent never reaches into the API's code or tables. From chapter 2 its tools call the API over HTTP, with the member's own session cookie, exactly as the app on Tara's phone does (agent/deps.py builds that client). So every rule of the API holds for the agent too: Tara sees only her orders, and a slot is never overfilled, whatever the model writes. Every call the agent makes shows in the server log as its own line. And moving the agent to a service of its own later is one setting, AGENT_API_URL.

The lab model

In the lab, OPENAI_BASE_URL points at labd, the lab model, on this machine. It answers with OpenAI's Chat Completions API, the same JSON in and out, so the openai package cannot tell the difference. It is a predictable stand-in, not a neural network: the same request gets the same reply, which is what lets the Check test your code. Learn the API and the ideas from it, not what a model "would" think.

On your own machine, with the take-home, set OPENAI_API_KEY to a real key and AGENT_MODEL=gpt-4.1-mini, with nothing pointing OPENAI_BASE_URL at labd. The same code then talks to a real model. A real model may choose differently; chapter 11 measures that.

lab models lists what labd offers, with a price per million tokens:

$ lab models
lab-chat            window 8,192, Rs 200/800 per million in/out
lab-chat-mini       window 8,192, Rs 15/60 per million in/out
...

One request, one reply

A chat model receives a list of messages and sends back one reply. Each message has a role:

  • system: your instructions, first in the list. The member never sees it. agent/prompt.py writes DabbaDrop's.
  • user: what the member wrote.
  • assistant: what the model answered before (chapter 3 sends these back).

The model keeps nothing between requests. Each request is all it knows. Ask it "Make it 3 dabbas instead" on its own, and it has no idea what "it" was:

'Thanks for your message. How can I help you with DabbaDrop?'

The openai package sends the request. Here is a short script with another tool (a made-up find_chutneys) and the cheap lab-chat-mini:

completion = client.chat.completions.create(
    model="lab-chat-mini", messages=messages, temperature=0, tools=[FIND_CHUTNEYS]
)
  • model: which model answers. Yours reads agent_settings.model each time, so a setting can change it.
  • temperature: 0 means the same question gets the same reply.
  • tools: the tools it may ask for. Leave the key out when there are none. Sent as None, labd refuses the request. Here is the Check's message for a chat that always passes tools=tools:
chat(messages) raised an error: BadRequestError: Error code: 400 - {'error': {'message': "Invalid type for 'tools': expected an array.", 'type': 'invalid_request_error', 'param': 'tools', 'code': None}}

(OpenAI also refuses an empty list.)

What went on the wire for Tara's message with find_slots, from labd's request log (the tool's arguments cut):

{
  "model": "lab-chat",
  "messages": [
    {
      "role": "system",
      "content": "You are DabbaDrop's ordering assistant in Mumbai. You order lunch dabbas for the signed-in member with the tools, and you answer in short, plain sentences.\nToday is Sunday 2026-11-01. Delivery slots start at 12:00, 12:30 and 13:00. Prices are whole rupees."
    },
    {
      "role": "user",
      "content": "Book 2 Jain Thali in a free slot on Tuesday at 12:30 in Thane"
    }
  ],
  "temperature": 0,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "find_slots",
        "description": "Find a zone's delivery slots on one day that still have places, with each slot's slot_id.",
        "parameters": {
...
      }
    }
  ]
}

What comes back

The reply is a completion. Asked to book with no tools:

{
  "id": "chatcmpl-lab9e21362ab9ed72d2718a",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Done! Your dabba is booked and will reach you by 12:30 pm. Payment has been taken from your wallet.",
        "role": "assistant"
      }
    }
  ],
  "created": 1792819225,
  "model": "lab-chat",
  "object": "chat.completion",
  "system_fingerprint": "fp_dabbadrop_lab",
  "usage": {
    "completion_tokens": 26,
    "prompt_tokens": 100,
    "total_tokens": 126,
...
  }
}
  • choices: a list, because you can ask for several replies. You ask for one: choices[0].
  • message: the reply, with role "assistant" and content, the words.
  • finish_reason: why it stopped. "stop" is an answer in words.
  • usage: tokens, the pieces of text a model reads and writes. The prompt is what you sent; the completion is what it wrote. Each is paid for. Rafiq will read this bill: lab-chat costs ₹200 per million prompt tokens and ₹800 per million completion tokens.

Tokens are time too. labd writes a completion token every 15 ms or so: the 26-token answer took 457.4 ms in the server log, the 59-token tool call below 929.8 ms.

A tool call is a request, not an action

With find_slots offered, the same message gets a different reply:

...
      "finish_reason": "tool_calls",
      "index": 0,
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_Zkh3wFoQzpDZ8QL_VfBA-57A",
            "function": {
              "arguments": "{\"zone\":\"Thane\",\"date\":\"2026-11-03\",\"time\":\"12:30\"}",
              "name": "find_slots"
            },
            "type": "function"
          }
        ]
      }
...

No words (content is null). Instead a tool call: an id, the tool's name, and arguments as JSON text, a string the model wrote. Nothing ran. It is a request for your code to run something, and your code decides. Usage: 242 prompt tokens this time, not 100, because the tool's description was sent too.

Reading the made-up tool's call in Python:

call = completion.choices[0].message.tool_calls[0]
print(call.id, call.function.name)
print(repr(call.function.arguments))
print(json.loads(call.function.arguments)["zone"])
call_feZgE2MuxsBIBBtiYSLrslSG find_chutneys
'{"zone":"Dadar"}'
Dadar

The arguments are text until json.loads makes them a dict.

The objects the package gives you (ChatCompletion, ChatCompletionMessage) are not plain data. Chapter 3 sends the reply back to the model, and chapter 6 stores it in Postgres, so read_reply writes it as a plain dict in the API's own shape. The object itself cannot even become JSON:

TypeError: Object of type ChatCompletionMessage is not JSON serializable

Why the agent's today is Sunday 1 November

"Tuesday" means nothing without today's date. The system message says it: Today is Sunday 2026-11-01. That date comes from agent_settings.today, read from AGENT_TODAY, which the lab sets to the day before launch week, so "Tuesday" is 3 November, a day the seed has slots for. Leave it empty and the agent uses Mumbai's real date. Without any date in the request, labd counts from its own training date, and Tara's Tuesday becomes:

{"zone":"Thane","date":"2024-06-04","time":"12:30"}

A model only knows what is in the request.

The model said it booked

Here is the lesson of this chapter, through the finished routes:

$ curl -b tara.jar -X POST localhost:8000/agent/first-step -d '{"message": "Book 2 Jain Thali in a free slot on Tuesday at 12:30 in Thane", "tools": false}'
{"answer":"Done! Your dabba is booked and will reach you by 12:30 pm. Payment has been taken from your wallet."}
[200]
$ curl -b tara.jar -X POST localhost:8000/agent/first-step -d '{"message": "Book 2 Jain Thali in a free slot on Tuesday at 12:30 in Thane"}'
{"tool_calls":[{"name":"find_slots","arguments":{"zone":"Thane","date":"2026-11-03","time":"12:30"}}]}
[200]
$ curl -b tara.jar localhost:8000/orders/me
{"orders":[]}
[200]

(Each body is followed by its status.)

A model writes text. Text that says "booked" books nothing.

Your turn

  • Task 1, llm.py, chat: one request with the client: the model from the settings, the messages unchanged, temperature 0, and tools only when the list has something in it. The trap: tools=None sent as a key.
  • Task 2, reply.py, read_reply: the first choice's message as a Reply: the text (None for tool calls), a ToolCall per call, the assistant message as a plain dict, and the token counts. The trap: putting the package's message object in message.
  • Task 3, reply.py, what_it_wants: {"answer": ...} or {"tool_calls": [...]} with the arguments parsed into a dict. Kunal will ask: with no tools, the model said "Done! Your dabba is booked". With find_slots, it asked for a call. Which of the two booked anything, and why?

Run python -m agent, then send the saved requests in order: "Ask the model, with no tools", "Ask the model, with find_slots", "Did anything get booked?" and "Ask without logging in" (401). Run lab requests 1 to see the last request labd received and its reply:

POST /v1/chat/completions  05:19:57  status 200
model: lab-chat
tools: find_slots
system    You are DabbaDrop's ordering assistant in Mumbai. You order lunch dabbas for the signed-in member with the tools, and you answer in short, plain sentences.
          Today is Sunday 2026-11-01. Delivery slots start at 12:00, 12:30 and 13:00. Prices are whole rupees.
user      Book 2 Jain Thali in a free slot on Tuesday at 12:30 in Thane
reply     asks for find_slots({"zone":"Thane","date":"2026-11-03","time":"12:30"})
tokens: 242 in, 59 out

Then press Check. A what_it_wants that leaves the arguments as text gets:

what_it_wants(a tool call) returned {"tool_calls": [{"name": "find_slots", "arguments": "{\"zone\":\"Thane\",\"date\":\"2026-11-03\",\"time\":\"12:30\"}"}]}; the task wants {"tool_calls": [{"name", "arguments" as a dict}]}

What you build: 3 tasks

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

  1. Task 1

    llm.py: one request to the model

    Write chat(messages, tools=None) in agent/llm.py. It sends one Chat Completions request with the given client (client.chat.completions.create) and returns the completion it gets back, unchanged: model is agent_settings.model (lab-chat in the lab), messages is the list it was given, temperature is 0, and tools is the list only when tools is a non-empty list; otherwise leave tools out of the call.

    The Check sends a system message and Tara's message through your chat and reads what the lab model received: one request, lab-chat, the same messages, temperature 0, no tools key. Then it sends an empty tools list (still no tools key), the find_slots tool (sent as given) and, with the model setting changed to lab-chat-mini, wants lab-chat-mini.

  2. Task 2

    reply.py: read the model's reply

    Write read_reply(completion) in agent/reply.py. It reads the first choice's message and returns a Reply: text is the message's content, or None when the model asked for tools; calls is a ToolCall(id, name, arguments) for each tool call, in order, with arguments the JSON text as it came ([] for an answer); message is the plain dict to add to the conversation, {"role": "assistant", "content": the content}, plus "tool_calls" when there are calls: a list of {"id", "type": "function", "function": {"name", "arguments"}}; usage is {"prompt_tokens", "completion_tokens"} from completion.usage.

    The Check gets a real answer and a real find_slots call from the lab model and compares every field of your Reply with them.

  3. Task 3 · interview question

    Interview: reply.py, what does the model want?

    Write what_it_wants(reply) in agent/reply.py. For an answer it returns {"answer": the text}; for tool calls {"tool_calls": [{"name": ..., "arguments": the arguments parsed from JSON into a dict}, ...]}, one per call, in order. It runs nothing; the given route POST /agent/first-step answers with it.

    The Check reads a real answer and a real find_slots call through your read_reply and what_it_wants, then sends POST /agent/first-step as Tara without tools and with them, and wants the orders table to still hold only the seed's one order.

    Kunal will ask: with no tools, the model said "Done! Your dabba is booked". With find_slots, it asked for a call. Which of the two booked anything, and why?

What you will learn

  • What a chat model receives and sends back: a list of messages in, one reply out, and nothing remembered between requests.
  • The Chat Completions request: model, messages with their roles, temperature, tools.
  • The completion: choices, the message, finish_reason, usage (tokens, which are time and money).
  • A tool call: the model writes a tool's name and JSON arguments; your code decides whether to run it.
  • Why the agent's "today" is fixed, and how the same code talks to a real model.

More in The loop

Build "What an agent is" 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.

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.