SyntaxPilot
Courses/AI: Zero to Agents/Lesson 32
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

AI: Zero to Agents · Lesson 32 of 40

Build your first agent in Python

queued

These are the notes for AI episode 32. In episodes 26 to 31 we invented the parts of an agent one by one. Here we put them together into a working train-ticket agent in plain Python, and watch each part fail first: a model that only talks, a wrong tool name, a tool that returns the wrong date (a viewer's question from the comments), a booking with nobody's permission, and a loop that never ends. Every Python example runs as-is in the SyntaxPilot compiler; outputs and errors are real (Python 3.13). The LLM is a toy (a few if rules) standing in for a real model call, so you can see exactly what the agent code does around it.

Real-life example: the travel agent at the station

At the travel agent's counter In our Python agent
"Mumbai to Pune, Saturday" the goal (the user's message)
He checks the train chart on his computer a tool: search_trains(date)
"Saturday is full. Shall I try Sunday?" a check on the tool result
"Shall I book it? Rs 450." Pays only after your yes human approval before an irreversible action

Problem 1: a model alone can only talk

The model writes what a booking usually looks like. It can't see the train chart and can't press a book button, so the "booking" is a hallucination: confident text with nothing real behind it.

def llm(question):               # toy LLM: no tools, only words
    return "Booked! Train 12127, seat B2-42, Sat 8 Nov. Rs 450."

question = "Book me Mumbai to Pune on Sat 8 Nov"
print("You    :", question)
print("Agent  :", llm(question))
print("Railway: PNR not found. Nothing was booked.")

Output:

You    : Book me Mumbai to Pune on Sat 8 Nov
Agent  : Booked! Train 12127, seat B2-42, Sat 8 Nov. Rs 450.
Railway: PNR not found. Nothing was booked.

The parts of an agent

Part What it does In our code
Think the model picks the next step llm(messages) returns a JSON action
Act your code runs a tool TOOLS[name](**args)
Observe read the tool's result result
Remember add the result to the history messages.append(...)
Stop a final answer or a step limit if "answer" in reply / range(1, 6)

The model never runs anything itself. It replies with data (which tool, which arguments) and your code decides whether and how to run it. That's why every safety check in this episode lives in your code.

goal ──▶ [ think: llm() ] ──▶ JSON action ──▶ [ act: run tool ] ──▶ result
              ▲                                                    │
              └────────────── messages (memory) ◀── observe ◀─────┘
                    stop when: answer · max steps · human says no

The fix: tools and a loop

A tool registry is just a dictionary from a tool's name to a Python function, so code can find the tool the model asked for.

import json
TRAINS = [{"no": 12127, "date": "8 Nov", "fare": 450}]
def search_trains(date): return [t for t in TRAINS if t["date"] == date]
def book(no): return f"PNR 4521 for train {no}"
TOOLS = {"search_trains": search_trains, "book": book}
def llm(messages):               # toy LLM: replies with a JSON action
    if len(messages) == 1:
        return json.dumps({"tool": "search_trains", "args": {"date": "8 Nov"}})
    if len(messages) == 2:
        return json.dumps({"tool": "book", "args": {"no": 12127}})
    return json.dumps({"answer": "Done! " + messages[-1]})
messages = ["Book me Mumbai to Pune on Sat 8 Nov"]
for step in range(1, 6):                       # at most 5 steps
    reply = json.loads(llm(messages))          # think
    if "answer" in reply:
        print("Agent:", reply["answer"]); break
    result = TOOLS[reply["tool"]](**reply["args"])   # act
    print(f"step {step}: {reply['tool']} {reply['args']} -> {result}")
    messages.append(str(result))               # observe + remember

Output:

step 1: search_trains {'date': '8 Nov'} -> [{'no': 12127, 'date': '8 Nov', 'fare': 450}]
step 2: book {'no': 12127} -> PNR 4521 for train 12127
Agent: Done! PNR 4521 for train 12127

The PNR is real this time, because a tool made it, not the model's imagination.

Problem 2: a wrong tool name crashes the loop

Models make small mistakes, like asking for find_trains when the tool is called search_trains.

import json
def search_trains(date): return [{"no": 12127, "date": date, "fare": 450}]
TOOLS = {"search_trains": search_trains}

def llm(messages):               # toy LLM: gets the tool name wrong first
    if len(messages) == 1:
        return json.dumps({"tool": "find_trains", "args": {"date": "8 Nov"}})
    if "ERROR" in messages[-1]:
        return json.dumps({"tool": "search_trains", "args": {"date": "8 Nov"}})
    return json.dumps({"answer": "Found: " + messages[-1]})

messages = ["Find trains Mumbai to Pune on 8 Nov"]
for step in range(1, 6):
    reply = json.loads(llm(messages))
    if "answer" in reply:
        print("Agent:", reply["answer"]); break
    result = TOOLS[reply["tool"]](**reply["args"])
    print(f"step {step}: {reply['tool']} -> {result}")
    messages.append(str(result))

Output:

Traceback (most recent call last):
  File "main.py", line 17, in <module>
    result = TOOLS[reply["tool"]](**reply["args"])
             ~~~~~^^^^^^^^^^^^^^^
KeyError: 'find_trains'

We trusted the model's tool name and indexed the dictionary directly. One typo and the whole agent dies.

The fix: a safe tool runner

Turn the failure into an observation the model can read, and list the real tools so it can correct itself (the same idea as episode 27).

import json
def search_trains(date): return [{"no": 12127, "date": date, "fare": 450}]
TOOLS = {"search_trains": search_trains}
def llm(messages):               # same toy LLM: wrong tool name first
    if len(messages) == 1:
        return json.dumps({"tool": "find_trains", "args": {"date": "8 Nov"}})
    if "ERROR" in messages[-1]:
        return json.dumps({"tool": "search_trains", "args": {"date": "8 Nov"}})
    return json.dumps({"answer": "Found: " + messages[-1]})
def run_tool(name, args):        # never crash: errors become observations
    if name not in TOOLS: return f"ERROR: no tool '{name}'. Tools: {list(TOOLS)}"
    return TOOLS[name](**args)
messages = ["Find trains Mumbai to Pune on 8 Nov"]
for step in range(1, 6):
    reply = json.loads(llm(messages))
    if "answer" in reply: print("Agent:", reply["answer"]); break
    result = run_tool(reply["tool"], reply["args"])
    print(f"step {step}: {reply['tool']} -> {result}")
    messages.append(str(result))

Output:

step 1: find_trains -> ERROR: no tool 'find_trains'. Tools: ['search_trains']
step 2: search_trains -> [{'no': 12127, 'date': '8 Nov', 'fare': 450}]
Agent: Found: [{'no': 12127, 'date': '8 Nov', 'fare': 450}]

Problem 3: the tool returns the wrong date (the viewer's case)

You want 8 Nov, but 8 Nov is full, and this booking API's search returns the first available train, whatever its date. The toy model trusts every tool result. (From here on, the toy LLM returns a Python dictionary directly instead of a JSON string, to keep the code short.)

TRAINS = [{"no": 12127, "date": "9 Nov", "fare": 450},   # 8 Nov is full
          {"no": 11007, "date": "9 Nov", "fare": 380}]
def search_trains(date):          # the booking API: "first available"
    return TRAINS[0]              # ...even when the date is different!
def book(no): return f"PNR 4521: train {no} booked"
TOOLS = {"search_trains": search_trains, "book": book}
def llm(messages):                # toy LLM: trusts every tool result
    if len(messages) == 1:
        return {"tool": "search_trains", "args": {"date": "8 Nov"}}
    if len(messages) == 2:
        return {"tool": "book", "args": {"no": 12127}}
    return {"answer": "Done! " + messages[-1]}
messages = ["Book Mumbai to Pune on Sat 8 Nov"]
for step in range(1, 6):
    reply = llm(messages)
    if "answer" in reply: print("Agent:", reply["answer"]); break
    result = TOOLS[reply["tool"]](**reply["args"])
    print(f"step {step}: {reply['tool']} -> {result}")
    messages.append(str(result))

Output:

step 1: search_trains -> {'no': 12127, 'date': '9 Nov', 'fare': 450}
step 2: book -> PNR 4521: train 12127 booked
Agent: Done! PNR 4521: train 12127 booked

No crash and no error, and the agent says "Done!". But the ticket is for Sunday 9 Nov. A successful call is not the same as the right result. Nobody compared the result with the goal.

The fix: validate every tool result in code

TRAINS = [{"no": 12127, "date": "9 Nov", "fare": 450}]
def search_trains(date): return TRAINS[0]      # same "first available" API

def check_train(train, wanted_date):           # never trust, always verify
    if train["date"] != wanted_date:
        return f"REJECTED: train {train['no']} runs {train['date']}, not {wanted_date}"
    return "OK"

wanted = "8 Nov"
train = search_trains(wanted)
print("tool said :", train)
verdict = check_train(train, wanted)
print("check     :", verdict)
if verdict == "OK":
    print("go ahead and book")
else:
    print("Agent: No seats on 8 Nov. Train 12127 has seats on 9 Nov. Shall I look at that?")

Output:

tool said : {'no': 12127, 'date': '9 Nov', 'fare': 450}
check     : REJECTED: train 12127 runs 9 Nov, not 8 Nov
Agent: No seats on 8 Nov. Train 12127 has seats on 9 Nov. Shall I look at that?

This is validation, a kind of guardrail: code that checks an agent's inputs and outputs against hard rules (dates, amounts, stations, names). Exact checks belong in code, not in a prompt. Asking the model "is this right?" can miss the same thing twice (the lazy critic of episode 31).

Check this in code Example rule
Date train["date"] == wanted_date
Money train["fare"] <= max_fare
Route train["from"] == "Mumbai" and train["to"] == "Pune"
Shape the result has the keys you need ("no", "date")

Problem 4: booking spends money

A wrong search costs nothing; you just search again. A wrong booking spends money and can't simply be undone: it's an irreversible action. So before any irreversible action the agent stops and asks a person. This is human in the loop.

def book(no): return f"PNR 4521: train {no} booked, Rs 450 paid"

def ask_human(action):               # irreversible? a person decides
    answer = input(f"Agent wants to: {action}. Approve? (yes/no) ")
    print(answer)
    return answer.strip().lower() == "yes"

train = {"no": 12127, "date": "8 Nov", "fare": 450}   # checked: date OK
action = f"book train {train['no']} on {train['date']} for Rs {train['fare']}"
if ask_human(action):
    print(book(train["no"]))
else:
    print("Not booked. Nothing was paid.")

Output (input: no):

Agent wants to: book train 12127 on 8 Nov for Rs 450. Approve? (yes/no) no
Not booked. Nothing was paid.

And with a yes:

def book(no): return f"PNR 4521: train {no} booked, Rs 450 paid"

def ask_human(action):               # irreversible? a person decides
    answer = input(f"Agent wants to: {action}. Approve? (yes/no) ")
    print(answer)
    return answer.strip().lower() == "yes"

train = {"no": 12127, "date": "8 Nov", "fare": 450}   # checked: date OK
action = f"book train {train['no']} on {train['date']} for Rs {train['fare']}"
if ask_human(action):
    print(book(train["no"]))
else:
    print("Not booked. Nothing was paid.")

Output (input: yes):

Agent wants to: book train 12127 on 8 Nov for Rs 450. Approve? (yes/no) yes
PNR 4521: train 12127 booked, Rs 450 paid

In the compiler, type the answer in the program-input box before you press Run. Ask for approval on actions that pay, send, delete or book, not on every search, or the agent becomes annoying and people start clicking "yes" without reading.

Problem 5: a loop that never ends

On 8 Nov there are no trains at all, and the toy model never gives up.

def search_trains(date): return []           # 8 Nov: no trains at all

def llm(messages):                           # toy LLM: never gives up
    return {"tool": "search_trains", "args": {"date": "8 Nov"}}

MAX_STEPS = 5
messages = ["Book Mumbai to Pune on 8 Nov"]
for step in range(1, MAX_STEPS + 1):
    reply = llm(messages)
    if "answer" in reply:
        print("Agent:", reply["answer"]); break
    result = search_trains(**reply["args"])
    print(f"step {step}: search_trains -> {result}")
    messages.append(str(result))
else:                                        # the loop never hit break
    print(f"Stopped after {MAX_STEPS} steps. Tell the user: no trains on 8 Nov.")

Output:

step 1: search_trains -> []
step 2: search_trains -> []
step 3: search_trains -> []
step 4: search_trains -> []
step 5: search_trains -> []
Stopped after 5 steps. Tell the user: no trains on 8 Nov.

Python's for ... else: the else block runs only when the loop finished without hitting break. Every agent needs a way to stop: a final answer, a step limit, or a human saying stop. Without one, each extra loop is another paid model call.

The full agent

All six parts in one program: a tool registry, the model, a safe runner, a check on every result (even the booking itself), human approval for irreversible tools, and memory plus a step limit. The model first tries the buggy first_free search, gets REJECTED, recovers with by_date, and books only after a "yes". Each tool is a lambda, a one-line function (lambda date: TRAINS[0] is the same as def first_free(date): return TRAINS[0]).

TRAINS = [{"no": 12127, "date": "9 Nov"}, {"no": 11007, "date": "8 Nov"}]
TOOLS = {"first_free": lambda date: TRAINS[0],                  # the buggy API
         "by_date": lambda date: next(t for t in TRAINS if t["date"] == date),
         "book": lambda no: {"pnr": 4521, "no": no, "date": "8 Nov"}}
def llm(msgs):                                    # toy LLM: picks the next step
    if len(msgs) == 1:         return "first_free", {"date": "8 Nov"}
    if "REJECTED" in msgs[-1]: return "by_date", {"date": "8 Nov"}
    if "pnr" in msgs[-1] or "said no" in msgs[-1]: return "answer", msgs[-1]
    return "book", {"no": 11007}
def check(res, date): return str(res) if res["date"] == date else f"REJECTED: runs {res['date']}"
def approved(name, args): a = input(f"Approve {name} {args}? "); print(a); return a == "yes"
msgs = ["Book Mumbai to Pune on 8 Nov"]
for step in range(1, 6):                          # loop, at most 5 steps
    name, args = llm(msgs)                        # think
    if name == "answer": print("Agent:", args); break
    if name not in TOOLS: obs = f"ERROR: no tool {name}"               # safe runner
    elif name == "book" and not approved(name, args): obs = "human said no"   # human
    else: obs = check(TOOLS[name](**args), "8 Nov")                     # act + verify
    print(f"step {step}: {name} -> {obs}"); msgs.append(obs)            # remember

Output (input: yes):

step 1: first_free -> REJECTED: runs 9 Nov
step 2: by_date -> {'no': 11007, 'date': '8 Nov'}
Approve book {'no': 11007}? yes
step 3: book -> {'pnr': 4521, 'no': 11007, 'date': '8 Nov'}
Agent: {'pnr': 4521, 'no': 11007, 'date': '8 Nov'}

And when the human says no:

TRAINS = [{"no": 12127, "date": "9 Nov"}, {"no": 11007, "date": "8 Nov"}]
TOOLS = {"first_free": lambda date: TRAINS[0],                  # the buggy API
         "by_date": lambda date: next(t for t in TRAINS if t["date"] == date),
         "book": lambda no: {"pnr": 4521, "no": no, "date": "8 Nov"}}
def llm(msgs):                                    # toy LLM: picks the next step
    if len(msgs) == 1:         return "first_free", {"date": "8 Nov"}
    if "REJECTED" in msgs[-1]: return "by_date", {"date": "8 Nov"}
    if "pnr" in msgs[-1] or "said no" in msgs[-1]: return "answer", msgs[-1]
    return "book", {"no": 11007}
def check(res, date): return str(res) if res["date"] == date else f"REJECTED: runs {res['date']}"
def approved(name, args): a = input(f"Approve {name} {args}? "); print(a); return a == "yes"
msgs = ["Book Mumbai to Pune on 8 Nov"]
for step in range(1, 6):                          # loop, at most 5 steps
    name, args = llm(msgs)                        # think
    if name == "answer": print("Agent:", args); break
    if name not in TOOLS: obs = f"ERROR: no tool {name}"               # safe runner
    elif name == "book" and not approved(name, args): obs = "human said no"   # human
    else: obs = check(TOOLS[name](**args), "8 Nov")                     # act + verify
    print(f"step {step}: {name} -> {obs}"); msgs.append(obs)            # remember

Output (input: no):

step 1: first_free -> REJECTED: runs 9 Nov
step 2: by_date -> {'no': 11007, 'date': '8 Nov'}
Approve book {'no': 11007}? no
step 3: book -> human said no
Agent: human said no

Swapping in a real model

  1. Replace llm() with a real API call (episode 23).
  2. Describe each tool: its name, what it does, its arguments (episode 28). The model replies with a tool call instead of text.
  3. Send the whole history back each turn: the model is stateless.
  4. Keep the checks, the approval and the step limit in your code. A prompt is a request; code is a rule.

Glossary

Term Meaning Example from this episode
Agent a model that chooses steps, with code that runs them in a loop the train-ticket agent
Hallucination confident output with nothing real behind it "Booked! seat B2-42" with no booking
Tool a function the agent can call to act or look something up search_trains(date)
Tool registry a dictionary from tool names to functions TOOLS = {"book": book}
Action the model's choice of tool and arguments, as data {"tool": "book", "args": {"no": 12127}}
JSON a text format for data that code can read '{"tool": "book"}'
Observation what the agent sees after acting the tool's result or error
Message history everything said and observed so far, sent each turn messages
Safe tool runner runs tools without crashing; errors become messages run_tool()
KeyError Python's error for a missing dictionary key KeyError: 'find_trains'
Validation checking data against exact rules check_train()
Guardrail a check that keeps an agent within safe limits reject the wrong date
Irreversible action an action you can't simply undo booking, paying, deleting
Human in the loop a person approves certain actions input("Approve? (yes/no)")
Lambda a one-line function without a name lambda no: {"pnr": 4521, ...}
Step limit the maximum number of loop turns MAX_STEPS = 5
for/else Python: else runs only if the loop didn't break "Stopped after 5 steps"
Stateless the model remembers nothing between calls send messages every time

Common mistakes

Mistake What you see Why Fix
No tools Agent : Booked! Train 12127... but nothing booked a model can only write text give it tools and a loop
TOOLS[reply["tool"]] KeyError: 'find_trains' trusted the model's tool name safe runner returns an error message
Using any tool result ticket for 9 Nov when you asked for 8 Nov result never compared with the goal validate results in code
Booking without asking Rs 450 paid without your OK irreversible action, no human approval before pay/send/delete/book
while True: searches forever, a bill for every call no way to stop MAX_STEPS + for/else
Rules only in the prompt the model ignores "never book without asking" once a prompt is a request enforce rules in code

Mini project: a cancel-and-rebook agent

Extend the full agent with a cancel(pnr) tool. The user says "move my 9 Nov ticket to 8 Nov". The agent must search by date, check the new train, ask approval to cancel, ask approval to book, and stop after 6 steps. Test it with a "no" for the cancel and make sure nothing is booked.

Practice

1. Add a fare limit to the check: Delhi to Agra on 15 Nov, at most Rs 600.

Solution
def check_train(train, wanted_date, max_fare):
    if train["date"] != wanted_date:
        return f"REJECTED: runs {train['date']}, not {wanted_date}"
    if train["fare"] > max_fare:
        return f"REJECTED: fare Rs {train['fare']} is over Rs {max_fare}"
    return "OK"

for train in [{"no": 12280, "date": "15 Nov", "fare": 950},
              {"no": 12002, "date": "15 Nov", "fare": 540},
              {"no": 12050, "date": "16 Nov", "fare": 500}]:
    print(train["no"], "->", check_train(train, "15 Nov", 600))

Output:

12280 -> REJECTED: fare Rs 950 is over Rs 600
12002 -> OK
12050 -> REJECTED: runs 16 Nov, not 15 Nov

2. Add a cancel tool that also needs a human's yes, and make an unknown tool safe.

Solution
def book(no): return f"PNR 4521: train {no} booked"
def cancel(pnr): return f"PNR {pnr} cancelled, refund Rs 400"
TOOLS = {"book": book, "cancel": cancel}
NEEDS_OK = {"book", "cancel"}          # both are irreversible

def run_tool(name, args, answer):      # answer = what the human typed
    if name not in TOOLS:
        return f"ERROR: no tool {name}"
    if name in NEEDS_OK and answer != "yes":
        return f"{name} not done: human said {answer!r}"
    return TOOLS[name](**args)

print(run_tool("cancel", {"pnr": 4521}, "no"))
print(run_tool("cancel", {"pnr": 4521}, "yes"))
print(run_tool("refund_all", {}, "yes"))

Output:

cancel not done: human said 'no'
PNR 4521 cancelled, refund Rs 400
ERROR: no tool refund_all

3. Why should the approval check be in code and not only in the system prompt?

Answer

A prompt is an instruction the model usually follows; code is a rule that always runs. If the model is confused, tricked by text in a tool result, or just makes a mistake, the code check still stops the booking.

4. Which of these need approval: search trains, check the date, book, send an SMS to the passenger, print the PNR?

Answer

Book (spends money) and send an SMS (can't be unsent). Searching, checking and printing are safe to repeat.

Quick quiz 1

Goal: Delhi to Agra, 15 Nov, max Rs 600. The tool returns {'no': 12280, 'date': '15 Nov', 'fare': 950}. What should the agent do?

Answer

B: reject it (the fare is over Rs 600) and tell the user. Check every rule, not just the date.

Quick quiz 2

Which step needs a human's OK? 1. search, 2. check the date, 3. book(11007) (pays Rs 380), 4. print the PNR.

Answer

C: step 3, the booking. It spends money and can't be undone.

Interview questions

  1. What is an AI agent, in code? A loop where a model chooses the next action (as structured data), your code runs the tool, and the result is fed back, until a final answer or a stopping condition.
  2. Why does the model return JSON instead of running tools itself? The model only produces text. Structured output lets your code parse the choice, validate it and decide whether to run it.
  3. How do you handle a hallucinated tool name? Never index the registry blindly; return an error observation listing the valid tools so the model can retry.
  4. A tool returns a successful but wrong result. How do you catch it? Validate results against the goal in code (dates, amounts, IDs) before acting on them.
  5. What is human-in-the-loop, and where do you put it? A person approves high-impact or irreversible actions (payments, bookings, deletes, sending messages), checked in code just before the tool runs.
  6. What stopping conditions should an agent have? A final answer, a maximum number of steps (and often a budget or timeout), and a human's "stop".

Summary

  • A model alone only talks: it can hallucinate a booking.
  • An agent = think, act, observe, remember in a loop, with tools in a registry.
  • Wrong tool names become error observations, not crashes.
  • Validate every tool result in code: success is not the same as correct.
  • Irreversible actions (book, pay, send, delete) need a human's approval.
  • Every agent needs a step limit.

Next: episode 33, Multi-agent systems: when one agent isn't enough.

Sources: Anthropic, "Building effective agents" (19 Dec 2024): agents as "LLMs using tools based on environmental feedback in a loop", with stopping conditions such as a maximum number of iterations; Anthropic tool-use documentation (episode 28). The viewer's wrong-date case came from a viewer's YouTube comment (29 Oct 2026).