The Research/Explore Agent

Chapter 1 already used a search agent as its very first concrete example of context isolation. This chapter goes deeper into designing that agent type properly — the fastest, most narrowly-scoped agent in this course, built purely to locate code and answer structural questions, and calibrated by how broad a search actually needs to be.

What a Research/Explore Agent Is For

This agent answers "where is X handled" or "how is Y structured" questions by searching a codebase and reporting back file paths, patterns, and structure — nothing more. It's distinct from Chapter 4's teaching agent: a teaching agent explains a concept once it's found, building understanding; a research agent's job stops at finding and reporting where and how something is structured, without necessarily explaining the deeper conceptual "why" behind it.

Designing a Research Agent's Definition

"Use this agent to locate where something is implemented, or to answer a factual question about the codebase's structure — especially when you're not confident you'll find the right match yourself in just a few tries. Not for making changes, and not for deep conceptual explanation." Tools are the clearest, most direct example of Chapter 1's isolation principle in this entire course: Read, Grep, and Glob only — no Edit or Write whatsoever, since this agent's entire job is finding and reporting, never changing.

Model choice here is a genuine trade-off, unlike most other agents in this course. A quick, narrow lookup can often use a faster, lighter model perfectly well. A genuinely wide, ambiguous search across an unfamiliar codebase — where the right search terms aren't obvious upfront — benefits from a more capable model able to reason about where to look next as each search comes back.

Search Breadth: Quick vs. Medium vs. Thorough

Specifying how broad a search should be helps a research agent calibrate its own effort correctly:

• Quick — a single targeted lookup, when you're fairly confident where the answer lives
• Medium — moderate exploration across a few likely locations
• Thorough — searching across multiple locations and naming conventions, for a genuinely uncertain or unfamiliar area of the codebase

Without this signal, a research agent might either under-search a genuinely hard question (stopping at the first plausible-looking match) or over-search a trivial one (spending effort exploring alternatives that were never really in doubt).

Writing the System Prompt for a Research Agent

A research agent's system prompt should instruct it to report exact file paths and line numbers — not vague locations like "somewhere in the auth folder" — to summarize findings concisely rather than dumping every raw search result verbatim, and to state honestly when it did not find a confident answer, rather than reporting an uncertain guess with unwarranted confidence.

Briefing a Research Agent Well

A good brief states the actual question clearly and, per the section above, the expected search breadth — "quick" for something you're fairly sure about, "thorough" for something genuinely unclear.

A Worked Example

"Find where rate limiting is implemented for the public API. I'm not sure whether it's applied per-endpoint or globally at the router level — a medium-depth search should be enough." This states the actual question, flags the genuine uncertainty driving the question (per-endpoint vs. global), and gives an explicit breadth expectation so the agent neither stops too early nor searches far wider than the question actually warrants.

Hands-On Exercises