A first agent that only reads

Your first agent should only be able to read. Not because writing is hard, but because a read-only agent teaches every important lesson at the lowest risk: you learn to write a goal, watch how the model picks tools, read its trace and count its cost, with nothing that can break.

Good tasks for a first read-only agent: building a list of decisions from a pile of minutes, finding every place a term is used in project documents, or explaining how a code folder is organised. Each needs several turns, because the agent must search, open and then read files based on what it finds. That is why the task suits an agent rather than a single prompt.

For a read-only agent, three kinds of tool are enough: find files by name, search text inside files, and read a file's content. No tool to write, run commands, open the internet or start a subagent (a second agent the main agent calls). Each extra tool is an extra capability you must watch, so do not grant one without a reason.

Place the agent in the sandbox from chapter two: a folder of document copies, on a machine or container that holds no secret files. Remember, a read-only agent can still leak: whatever it reads enters the context, is recorded in the trace and is sent to the model provider. If that folder holds a file with keys or passwords, reading alone is enough to spread it.

Limits go in from the very first run, not after something goes wrong. There are three different limits, and all three are needed:

• Turn limit: the maximum number of cycles of the model picking a tool and reading the result. For summarising one small folder, ten to fifteen turns is usually enough. If the limit is reached, that signals an unclear goal or an oversized task, not a reason to raise the limit.
• Budget limit: the maximum cost of one task in money. This protects you from a loop that keeps reading large files.
• Output limit: the maximum number of tokens the model may write in one answer. Do not set it too low: reasoning models spend part of this budget thinking, and a limit that is too tight can produce empty answers.

Besides limits, set a checkable goal and a result shape before running: for example "a list of decisions, one line per decision, with its source file name". A shape that names sources lets you check each line against its file. Without it, you can only trust.

As a worked example, here is a read-only agent with the Claude Agent SDK for Python (package claude-agent-sdk). tools makes only three read tools available, allowed_tools lets them run without asking, and permission_mode="dontAsk" refuses any other call that would ask. Without tools, dontAsk alone still lets through calls that need no approval, such as read-only shell commands and starting a subagent. The max_turns and max_budget_usd options set the turn and budget limits, and cwd sets the working folder:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    options = ClaudeAgentOptions(
        tools=["Read", "Glob", "Grep"],
        allowed_tools=["Read", "Glob", "Grep"],
        permission_mode="dontAsk",
        max_turns=12,
        max_budget_usd=0.50,
        cwd="minutes-copy",
    )
    tugas = "I need a list of decisions from the minutes in this folder, with the source file name for each decision."
    async for message in query(prompt=tugas, options=options):
        if isinstance(message, ResultMessage):
            print(message.result)
            print("cost", message.total_cost_usd, "turns", message.num_turns)

asyncio.run(main())

The last message from query() is a ResultMessage holding the final result, the cost estimate and the number of turns. The working folder is not a wall: run this example on a machine or container that holds only the document copies. A step specific to Anthropic; check the latest version in its documentation, because option names can change.