Build a Research Agent

Every module in this path has been building toward one question: what does a reliable agentic system actually look like when you run it for real? This capstone answers that with the same pattern I use in my SDLC harness — a linear task-orchestration agent that runs on my Mac Mini, driven by a plain Markdown spec file.

The agent does four things, in strict order:

1. Read a spec — the task description lives on disk as a plain text file.
2. Plan with Claude — ask claude-sonnet-4-6 to decompose the spec into numbered steps.
3. Execute each step — one tool call per step, with the full history passed forward.
4. Write a status report — summarize what was done.

No parallel subtasks, no handoff between specialized agents, no orchestration framework. The simplicity is the point. Module 06 gives you the theory for why this works; this module gives you the working code.

Think of the agent like a contractor who reads a project brief, writes a numbered to-do list, works through it top-to-bottom while keeping notes on each completed item, and then files a completion report. The notes carry forward — every item on the list is informed by everything done before it. That is the shared-context principle made concrete.

The agent starts with a plain-text spec file. In the SDLC harness this is a Markdown task description; for this module any text file describing a task will work.

Copy this block, create a task-spec.md with any task description, and run it. The client object is all you need — no additional SDK wrapping. This is your first runnable step, and it verifies your ANTHROPIC_API_KEY before you write any more code.

Once the spec is loaded, the agent asks Claude to decompose it into a numbered list of steps. The prompt is deliberately minimal — we want a clean step list, not prose explanation.

The parser is simple: any line starting with a digit is a step. Production harnesses often ask for structured JSON output and parse that instead, but plain text is easier to inspect when you are getting the system running for the first time.

Mid-Module Checkpoint

Before moving on, predict: what does response.content[0].text hold after the plan_steps call above? The model's generated numbered step list — not a token count, not the system prompt, not the raw HTTP response. Add print(raw) before the list comprehension and run it against a real spec to confirm.

The agent needs to do things — read files, write files, run commands. In the Anthropic SDK, tools are defined as JSON schemas that describe what each tool accepts. Think of a tool definition like a job description you hand to a new contractor: a name, what the role does, and what information they need to start.

Now add the dispatch function that routes a tool-call block to its real implementation:

Two tools, one dispatch function, eleven lines. Module 03 showed you how to extend this incrementally — adding a run_command tool follows exactly the same pattern. Start with the minimum tools the task requires and add more only when you have evidence a capability is missing.

The execution loop is where the path's core thesis becomes code. Each step receives the full history of every completed step before it — not a summary, not a filtered view — so the model's decisions are always grounded in what already happened.

Notice that context["history"] grows with every call. Step 3 can see steps 1 and 2 in full detail. That is what makes the outputs coherent — no step is working blind. When no tool_use block appears, the model's text response is treated as the step result and appended to history so that later steps still see it.

Reflective Checkpoint

What would break if you ran all steps in parallel instead of sequentially?

Each step would start with an empty history. Step 3 could not know that step 1 already created the file it is supposed to read. Steps would conflict or duplicate work, and the final report would be incoherent — exactly the failure mode module 06 describes in the multi-agent trap. Sequential with shared context produces better output, even when parallel looks faster on paper.

When all steps finish, the agent asks Claude to turn the accumulated history into a human-readable status report, then writes it to disk.

The report summarizes what the agent actually did, not what it planned to do. If step 2 failed to find a file, the history captured that failure, and the report reflects reality. This honest audit trail is what makes the system trustworthy enough to use for real work.

Now assemble the four stages into a single run_task_agent function. Each stage calls a function you have already seen — no new logic, just composition in order.

This is the complete agent. Four stages, six functions, one linear pass through the spec. The SDLC harness I run on my Mac Mini follows this exact shape — the production version adds a retry wrapper around execute_step and writes structured logs, but the core loop is identical.

How This Connects to Module 06

Module 06 will explain why this architecture is reliable: the relay-race principle (each step hands the baton — the full context — to the next runner), and why multi-agent systems fail when that handoff is broken. What you built here is the practical demonstration of the theory.

The exercise below extends the capstone with a human-confirmation gate before the report is written — the same checkpoint pattern from module 04, applied at the exact moment where a mistake would be hardest to undo.