Wire it all together — a working CLI agent

You can read what AI wrote, catch what it got wrong, and direct it deliberately. You know the messages pattern, the agent loop, MCP, structured output, eval-driven development, secrets hygiene, prompting craft, and the full vocabulary of agent traces.

Time to assemble it. This chapter is seven lessons. You pick a project that can actually ship, then you write a working command-line AI agent — runs in Pyodide in your browser, calls fake tools that mimic real ones, loops on stop reasons, logs every turn, ships a clean exit when it's done. About a hundred lines of Python, end-to-end. The last lesson is the optional ML-system portfolio track.

Why this mid-path build matters more than the polish

You can read about agents for a year and still not really get them. The first time you build one, the patterns lock in. The first time your loop hits the tool_use branch and you watch your code dispatch to the right tool and feed the result back into the model — that's the moment the abstraction becomes intuition. From there, every framework you'll ever touch reads obvious.

That's the goal of this chapter. Not to ship something you'd put in production — production agents have observability, retries, distributed state, eval guardrails, prompt versioning. To ship something that proves you understand what's underneath.

What this mid-path agent does

A small CLI tool. The user types a question. The agent has access to two tools (a fake read_file and a fake write_file that operate on an in-memory dict, since we're in a browser). The agent loops:

1. Send the user's question to the model with the tool definitions.
2. If the model returns stop_reason: "tool_use", parse the tool call, dispatch to the matching Python function, append the result to the message history, loop.
3. If the model returns stop_reason: "end_turn", take the final text and print it.
4. Cap at five turns to avoid runaway loops.

Read that paragraph again. That's the entire agent. The hundred lines of code in the CLI agent lesson are an expansion of that paragraph plus error handling plus a max-turns guard.

The CLI agent lesson, in 12 steps

• Steps 1-3: read the existing tool-loop pattern and understand the message-history append rules.
• Step 4: predict the agent's output for a given input, before you've written any code.
• Step 5: fill in the stop-condition check.
• Steps 6-7: fix two AI-shipped bugs in the dispatch path.
• Step 8: read the logging pattern that makes the agent debuggable.
• Step 9: write the tool runner — the function that maps tool names to Python callables.
• Step 10: fix the loop-exit condition.
• Step 11: write the full agent.
• Step 12: checkpoint — the agent runs end-to-end on a real test case and prints the right answer.

What AI specifically gets wrong building agents

The build bakes in the three top patterns from the wedge:

1. The two-message append. Cursor reliably appends only the tool_result and forgets the assistant's tool_use block. Result: the model on the next turn has no memory of asking for the tool. It asks again. Tool loop. Step 7 of the CLI agent lesson is fixing exactly this.

2. Wrong loop-exit condition. AI writes while True: ... break or while turn < 100, missing the natural exit on stop_reason == "end_turn". Result: the loop either never exits or exits one turn too early. Step 10 of that lesson fixes it.

3. Tool dispatch by string equality with no fallback. AI writes if tool_name == "read_file": ... and forgets the unknown-tool case. The first time the model hallucinates a tool name, the agent silently does nothing and returns no answer. Step 6 of that lesson is the fix.

These are the three bugs that ship most often into AI-generated agent code. By the end of that lesson's twelve steps you'll have written each of them wrong, fixed each of them right, and seen the difference in output.

What you'll be able to do at the end

By the end you'll have:

• Written a working AI agent loop in Python from memory.
• Logged every turn (input, tool calls, outputs, stop reasons) with enough detail to debug a failure.
• Spotted the three top "AI ships agent code wrong" patterns at sight.
• Built mental scaffolding for every framework you'll touch — LangGraph, the Vercel AI SDK, Claude's Agent SDK, OpenAI's Assistants API, every house-built agent runtime. They're all dressed-up versions of what you wrote here.

This chapter is a mid-path build — a path checkpoint, not a finish line. On the developer route, harnesses, image, video, and production tooling still follow. You're not an AI engineer after this build alone; that takes more production reps than any course can teach. But you're past the ceiling that was blocking you. You can read agent traces, catch agent bugs, and ship features without flinching.

Press Start chapter below.