Prompting for Agents: Steering Models That Act

You’ll build a minimal but real agent: a codebase analyst that answers questions about any local project by listing and reading files in a loop — every concept from this lesson in ~80 lines.

Step 1 — Set up

mkdir mini-agent && cd mini-agent
python3 -m venv .venv && source .venv/bin/activate
pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

Step 2 — Define tools and guardrails

Create agent.py. Note: both tools are read-only — the guardrail is structural.

import sys
from pathlib import Path

import anthropic

ROOT = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()

TOOLS = [
    {
        "name": "list_files",
        "description": "List files under a relative directory of the project. "
        "Use this FIRST to orient yourself before reading anything.",
        "input_schema": {
            "type": "object",
            "properties": {"path": {"type": "string", "description": "Relative dir, '' for root"}},
            "required": ["path"],
        },
    },
    {
        "name": "read_file",
        "description": "Read one file's content (truncated to 8000 chars). "
        "Prefer reading few, well-chosen files over reading everything.",
        "input_schema": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
]

def run_tool(name: str, args: dict) -> str:
    target = (ROOT / args["path"]).resolve()
    if not target.is_relative_to(ROOT):          # guardrail: never escape the project
        return "Error: path outside project root."
    if name == "list_files":
        if not target.is_dir():
            return f"Error: {args['path']!r} is not a directory."
        entries = [
            p.name + ("/" if p.is_dir() else "")
            for p in sorted(target.iterdir())
            if p.name not in {".git", "node_modules", ".venv", "dist"}
        ]
        return "\n".join(entries) or "(empty)"
    if name == "read_file":
        if not target.is_file():
            return f"Error: {args['path']!r} is not a file."
        return target.read_text(errors="replace")[:8000]
    return f"Error: unknown tool {name}"

Step 3 — Write the agent prompt (heuristics + budget + an out)

SYSTEM = """You are a codebase analyst agent. Answer the user's question about
the project by exploring it with your tools.

Heuristics:
- Orient first: list the root, then drill into promising directories.
- Read selectively. README, config and entry-point files usually answer
  structural questions fastest.
- Budget: simple questions should need under 8 tool calls; never exceed 15.
- If you cannot find the answer, say exactly what you looked at and what is
  missing. Never invent file contents.

When you have enough evidence, stop exploring and answer concisely, citing
file paths."""

Step 4 — The loop itself

client = anthropic.Anthropic()

def agent(question: str) -> str:
    messages = [{"role": "user", "content": question}]
    for _ in range(15):  # hard ceiling backing up the soft budget
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=2000,
            system=SYSTEM,
            tools=TOOLS,
            messages=messages,
        )
        if response.stop_reason != "tool_use":
            return "".join(b.text for b in response.content if b.type == "text")
        messages.append({"role": "assistant", "content": response.content})
        results = [
            {
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": run_tool(block.name, block.input),
            }
            for block in response.content
            if block.type == "tool_use"
        ]
        for block in response.content:           # watch the transcript while you build
            if block.type == "tool_use":
                print(f"  ⚙ {block.name}({block.input})", file=sys.stderr)
        messages.append({"role": "user", "content": results})
    return "Stopped: tool-call budget exhausted."

if __name__ == "__main__":
    print(agent(input("Question about this codebase: ")))

Step 5 — Run it and watch it think

python3 agent.py /path/to/any/project
# Question: How is this project built and deployed?

Expected result: stderr shows the loop in action — list_files(''), then targeted reads of README/config files, then a cited answer. Note how it orients first: that behavior came from one heuristic line in the system prompt. Delete that line and run again to watch the quality drop — you just did your first agent-prompt ablation.

Step 6 — Evaluate like the talk says

Write 5 questions about a repo you know well, with expected answers. Run them, grade answer-correctness (right/wrong), and read the worst transcript. Fix it by adding one heuristic, not by scripting steps. That loop — eval, read transcript, refine heuristic — is agent engineering.