Day 120 · An intern with a to-do list

Agents I — The Loop

You will be able to

Define an agent as LLM + tools + loop and identify each part in running code
Implement the ReAct-style loop: decide → act → observe → decide, with tool errors fed back as observations
Enforce stopping criteria and budgets (steps, tokens, time) and explain why every agent needs them
Apply the when-NOT-to-build-an-agent checklist to three candidate tasks

Today's ~120 minutes

Spaced-rep: due cards + restate the capstone brief from memory (D119)	10 min
ELI5 + tech read; agent-loop visualizer lap by lap	20 min
Guided: build the loop + agent-or-not verdicts	42 min
Practice: the grep tool upgrade	20 min
Project: refactor into agent/core.py with tests	20 min
Quiz + flashcards	8 min

Builds on: Day 111 — Tool use & function calling · Day 106 — LLM APIs — the request · Day 113 — RAG architecture

The analogy

🧸 ELI5⚙ Tech

On Day 111 you gave the polymath hands: it could call one tool when you asked one question. An agent is the next step — an intern with a to-do list and permission to keep working. You say "find out which config file sets our API rate limit," and the intern doesn't answer from memory. She walks to the filing room, lists the folders, opens the likely one, reads it, doesn't find it, opens the next, finds the line, and comes back with the answer AND how she got it.

The magic isn't intelligence — it's the loop. Look at the situation, pick ONE next action, do it, look at what happened, repeat. Each trip around the loop the intern knows more than the last trip, because the results of her actions pile up in her notes. And crucially, a good intern knows when to stop: when she has the answer, when she's out of places to look ("I checked every file — it isn't there"), or when she's spent too long ("this is taking hours, let me check in"). An intern with no stopping rule reorganizes the filing room until midnight. Yours will too, unless you build the clock in.

Why this matters on the job

"Agentic" is the most-hyped word in AI engineering, and the fastest way to stand out — in interviews and with customers — is demonstrating you know what the word mechanically means: a while-loop around an LLM that chooses tool calls, with observations accumulating in context. Every agent product you'll ever debug (coding agents, support agents, research agents) is this loop wearing different tools. FDEs also field the opposite conversation weekly: a customer wants "an agent" for a task that is actually a 3-step fixed pipeline — cheaper, faster, testable. Knowing when NOT to build the loop is billable judgment. Days 121–126 all build on the file you write today.

Watch it happen

An intern with a to-do list — the agent loop, step by step

step 1 / 5

goal

diagnose order #4412, draft reply

scratchpad

(empty)

tools

lookup_order(id)

search_docs(q)

draft_email(text)

Task: "Find why order #4412 failed and draft a reply." The agent holds a goal, a scratchpad, and tools.

🎯 Predict modespeed1×

Guided practice

guided 1

Build the loop: a file-Q&A agent in 70 lines

30 min

Create agent_v0.py with the starter code. It has all three parts labeled: TOOLS (three real functions over an in-memory filesystem), a ScriptedLLM (a deterministic stand-in policy so the LOOP runs in-browser — locally you swap in your Day 107 client and the Day 111 tool-use API, and nothing else changes), and run_agent, the loop itself.
Run task 1: "Which config file sets the API rate limit, and to what value?" Read the printed trace lap by lap: list_files → read the likeliest file → not there → read the next → found → final answer. Notice the answer cites the file it actually read.
Run task 2: "What is the database password?" — it is nowhere in the corpus. Watch the agent read everything, then give the honest give-up answer. Circle where in the ScriptedLLM that honesty lives (the fallback branch) — with a real LLM, that behavior comes from the system prompt: "if the information is not found after checking plausible files, say so."
Break a tool: rename a file in FS so the scripted policy requests a missing file, and confirm the TOOL ERROR comes back as an observation and the loop continues rather than crashing. Errors are observations.
Set max_steps=2 and rerun task 1: budget exhaustion fires mid-investigation. This is the seatbelt — leave it on.

🐍 python — editable, runs in your browser

# agent_v0.py — LLM + tools + loop. Grows on D121 (planner), D122 (memory),
# D125 (guards), D126 (triage). ScriptedLLM stands in for a real model so the
# loop mechanics run anywhere; swap in the D111 tool-use API locally.
FS = {
    "README.md":     "Nimbus Insights service. See settings for configuration.",
    "app.py":        "from settings import load\nconfig = load()\n# serves /v1/query",
    "settings.yaml": "workers: 4\nrate_limit: 120   # requests/min per key\nretries: 3",
    "notes.txt":     "TODO: move rate limiting to the gateway next quarter.",
}

# --- TOOLS: the agent's hands. The model never touches FS directly. ---
def list_files():
    return sorted(FS)

def read_file(name):
    if name not in FS:
        raise FileNotFoundError(f"no such file: {name}")
    return FS[name]

TOOLS = {"list_files": list_files, "read_file": read_file}

# --- the "LLM": a deterministic policy over (task, history) ---
class ScriptedLLM:
    def _needle(self, task):
        # a real model infers what to look for; we script that inference
        for w in ["rate", "password", "quota", "workers"]:
            if w in task.lower():
                return w
        return None
    def decide(self, task, history):
        needle = self._needle(task)
        listed = [h for h in history if h["tool"] == "list_files"]
        if not listed:
            return {"tool": "list_files", "args": {}}
        # if any read observation contains the sought line, answer from it
        for h in history:
            if h["tool"] == "read_file" and needle and needle in str(h["obs"]):
                line = [l for l in str(h["obs"]).splitlines() if needle in l][0]
                name = h["args"]["name"]
                return {"tool": "final_answer",
                        "args": {"text": f"{name} sets {line.strip()}"}}
        files = listed[0]["obs"]
        seen = {h["args"].get("name") for h in history if h["tool"] == "read_file"}
        # heuristic the prompt would induce: config-ish files first
        ordered = sorted(files, key=lambda f: ("settings" in f or "config" in f), reverse=True)
        for f in ordered:
            if f not in seen:
                return {"tool": "read_file", "args": {"name": f}}
        return {"tool": "final_answer",
                "args": {"text": "Checked every file; the information is not there."}}

# --- THE LOOP ---
def run_agent(llm, tools, task, max_steps=8):
    history = []
    for step in range(1, max_steps + 1):
        action = llm.decide(task, history)                 # 1. decide
        if action["tool"] == "final_answer":
            print(f"step {step}: FINAL -> {action['args']['text']}")
            return action["args"]["text"]
        fn = tools.get(action["tool"])
        try:                                               # 2. act
            obs = fn(**action["args"]) if fn else f"unknown tool {action['tool']}"
        except Exception as e:
            obs = f"TOOL ERROR: {e}"                       # errors are observations
        history.append({"tool": action["tool"], "args": action["args"], "obs": obs})
        print(f"step {step}: {action['tool']}({action['args']}) -> {str(obs)[:60]}")
    return "STOPPED: step budget exhausted"                # 3. the seatbelt

print("--- task 1 ---")
run_agent(ScriptedLLM(), TOOLS, "Which config file sets the API rate limit, and to what value?")
print("\n--- task 2: not in the corpus ---")
run_agent(ScriptedLLM(), TOOLS, "What is the database password?")

Ctrl/⌘+Enter runs · Tab indents · numpy/pandas/sklearn auto-load on import (torch and network calls need a local run)

guided 2

Agent or not? Three verdicts

12 min

For each task below, decide: agent, fixed workflow, or plain RAG — then write the one-sentence justification. Check against the key only when done.

"Every Monday, pull last week's tickets, summarize by category, email the report." Same steps every time, zero exploration.
"Find why the staging deploy is failing." Unknown cause; next action depends on each log you read.
"Answer employee policy questions from the handbook." One retrieval + one grounded generation per question.

Key: 1 = fixed workflow (the path is knowable in advance — an agent adds variance to a task that tolerates none); 2 = agent (genuinely open-ended investigation, the D120 loop's home turf); 3 = plain RAG (your capstone! — no loop needed until questions require multi-hop, and even then Day 118's decomposition may suffice). If you said "agent" for all three, reread the checklist — that instinct is the expensive one.

On your own

Teach the agent a new trick without touching the loop

20 min

Add a third tool grep(pattern) that returns {filename: [matching lines]} across all of FS, and extend the ScriptedLLM to prefer one grep over reading files one by one for "find the line" tasks. Then run the rate-limit task again and compare traces: the grep-enabled agent should finish in 2 steps instead of 3-4.

Constraints: run_agent must not change at all — that is the point of the tool abstraction; only TOOLS and the policy change. Hints: policy order — grep first if no grep observation exists; answer from the grep observation if it hits; fall back to read_file. Note what you just felt: better tools shrink the loop. That lesson — invest in tools, not cleverer loops — is half of agent engineering.

Ship before you stop

agent_v0 becomes a module

Refactor today's lab into a committed module the rest of Week 18 builds on: agent/core.py with run_agent(llm, tools, task, max_steps, on_step=None) — the on_step callback receives each (step, action, obs) for logging (Day 125's audit trail will hook in here); agent/tools_fs.py with the three file tools plus docstrings written as if for the model (they become tool descriptions in the real API); and tests/test_loop.py with four pytest cases: happy path finds the answer, honest give-up on absent info, tool error fed back as observation (loop continues), and max_steps stops a runaway policy (write a deliberately stuck ScriptedLLM for this). Include a README section mapping each piece to its real-LLM equivalent.

Rubric — check what you completed (0/6)

run_agent is tool-agnostic and policy-agnostic; nothing in it references filesAll four tests pass, including the deliberately-stuck-policy budget testTool errors surface as observations, never as crashesTool docstrings are written as model-facing descriptions (what, args, returns, when to use)README maps ScriptedLLM → real tool-use API swap explicitlyCommitted to the practice repo

Common mistakes & misconceptions

Letting the model "execute" tools. The model only ever emits a request; your code validates and executes. Blurring this line is how agents delete files nobody asked them to.
Hiding tool errors from the model. A swallowed exception leaves the agent reasoning from a stale world-model; the error string IS the steering signal for the next lap.
Shipping a loop with no budget "because it terminates in testing." Production inputs find the infinite loop; max steps, cost caps, and timeouts are day-one requirements, not hardening.
Treating an honest "not found" as a failure to prompt away. Calibrated give-ups are a success mode; punishing them breeds confident fabrication — the worst agent behavior.
Building an agent where a workflow suffices. If you can write the step sequence down in advance, do that — cheaper, faster, testable, explainable to the customer.
Growing the loop instead of the tools. A grep tool beat a smarter policy today; when an agent flails, upgrade its tools and their descriptions before touching the loop.

Knowledge check

Q1. What are the three components that make something an agent, per today's definition?

Q2. A tool call throws an exception mid-run. The correct handling is…

Q3. A customer wants "an agent" to generate the same three-section weekly report from the same two data sources. Your recommendation?

Go deeper — curated resources

articleAnthropic — Building Effective Agents (workflows vs agents) ↗30 min articleLilian Weng — LLM Powered Autonomous Agents (loop & tools sections) ↗30 min docsClaude Docs — Tool Use overview (the real API for the swap) ↗20 min

If you have a third hour

ReAct paper (Yao et al. 2022) ↗ — The origin of reason-act interleaving. Skim §2 and the Wikipedia-QA traces; you built exactly this today, minus the academic benchmarks.

Done means

Loop runs both tasks; honest give-up and budget stop both demonstrated
Tool-error experiment run: loop continues with the error as observation
All three agent-or-not verdicts match the key with sound reasoning
agent/core.py committed with four passing tests
Quiz ≥ 2/3

How this connects

← Back: Day 111's tool loop was one lap; today you closed it into a cycle. The honest give-up is Day 113's "insufficient context" escape hatch reborn as agent behavior.

Forward →: Day 121 adds a planner on top of this exact module, Day 122 gives it memory, Day 125 hardens it, and on Day 126 it triages support tickets with your capstone's retrieval as one of its tools.

Unlocks: D121 Agents II — Planning & Decomposition · D122 Agents III — Memory & Context · D123 Multi-Agent & Workflow Patterns · D124 Model Context Protocol