The agent loop in 60 lines
An agent is a model calling tools in a loop until it decides it is done. That is the whole idea. The loop itself is about 25 lines. Everything else in this note, and most of this course, is what you wrap around it so it fails safely.
The loop
- Send the task, the tool schemas and the history to the model.
- If the response asks for tools (
stop_reason == "tool_use"), run them and append the results as the next user message. - Otherwise the response is the answer. Return it.
About 60 lines, tools and all
This uses the Anthropic Messages API shape. OpenAI's function calling differs in names but not in structure: the model asks, you execute, you send the result back.
import os
from pathlib import Path
import anthropic
client = anthropic.Anthropic()
MODEL = os.environ["AGENT_MODEL"]
MAX_STEPS = 12
ROOT = Path(".").resolve()
TOOLS = [
{
"name": "read_file",
"description": "Read a UTF-8 text file under the working directory. Returns at most 20000 characters. Call list_dir first if you do not know the path.",
"input_schema": {
"type": "object",
"properties": {"path": {"type": "string", "description": "Relative path, for example src/main.py"}},
"required": ["path"],
},
},
{
"name": "list_dir",
"description": "List the entries of a directory under the working directory. Directories end with a slash.",
"input_schema": {
"type": "object",
"properties": {"path": {"type": "string", "description": "Relative path, default is the root"}},
},
},
]
def safe(path: str) -> Path:
target = (ROOT / path).resolve()
if not target.is_relative_to(ROOT):
raise ValueError(f"{path} is outside the working directory. Use a relative path inside it.")
return target
def read_file(path: str) -> str:
return safe(path).read_text()[:20000]
def list_dir(path: str = ".") -> str:
return "\n".join(sorted(p.name + ("/" if p.is_dir() else "") for p in safe(path).iterdir()))
FUNCS = {"read_file": read_file, "list_dir": list_dir}
def run_tool(block) -> dict:
try:
content = FUNCS[block.name](**block.input)
return {"type": "tool_result", "tool_use_id": block.id, "content": content}
except Exception as exc:
message = f"{type(exc).__name__}: {exc}"
return {"type": "tool_result", "tool_use_id": block.id, "content": message, "is_error": True}
def run_agent(task: str) -> str:
system = "You are a careful code-reading assistant. Check facts with tools before you answer."
messages = [{"role": "user", "content": task}]
for step in range(MAX_STEPS):
resp = client.messages.create(
model=MODEL, max_tokens=2000, system=system, tools=TOOLS, messages=messages
)
messages.append({"role": "assistant", "content": resp.content})
if resp.stop_reason != "tool_use":
return "".join(b.text for b in resp.content if b.type == "text")
calls = [b for b in resp.content if b.type == "tool_use"]
print(f"step {step + 1}: {[c.name for c in calls]}")
messages.append({"role": "user", "content": [run_tool(c) for c in calls]})
return "stopped: step limit reached"
if __name__ == "__main__":
print(run_agent(input("task> ")))
What each part is for
- Append the assistant message before the results. The API needs the
tool_useblocks in history so eachtool_resulthas something to answer. - Results go in one user message, results first. If the model made two calls, send two
tool_resultblocks together. Any text goes after them, never before. - Errors are results. A failed tool returns
is_error: trueand a message that says what to try next. The model reads it and adapts. An uncaught exception just kills your run. - The path check is a security boundary, not a nicety. The model chooses the arguments. Treat them like input from a stranger.
MAX_STEPSis the seatbelt. Without it, a confused model loops until your budget does.
Reason, then act
The pattern has a name: ReAct (Yao et al., 2022). The model interleaves a short thought, an action (a tool call) and an observation (the result), and the observation shapes the next thought. Modern APIs bake this in. The thought is the text before the tool_use block, or hidden reasoning if you enable it; the action and observation are the tool call and its result. You do not need a special prompt format. You do need to keep the text blocks in history, because they are the model's own plan and it reads them again on the next step.
Two practical details. First, a model can request several tools in one turn when the calls are independent. Run them concurrently if you can and return all the results in one message; that saves whole round trips. Second, a turn can end for reasons other than tool use or a final answer: the output hit max_tokens, or the model refused. Check stop_reason and handle those cases, or you will treat a truncated answer as a finished one.
Why agents are hard: errors compound
If each step succeeds with probability $p$ and steps are independent, a task of $n$ steps succeeds with probability
$$P = p^{n}$$
- $p = 0.99$, $n = 10$: $0.904$.
- $p = 0.99$, $n = 20$: $0.818$.
- $p = 0.95$, $n = 10$: $0.599$.
- $p = 0.95$, $n = 20$: $0.358$.
A step that is right 95 percent of the time sounds excellent, and twenty of them fail two times in three. Steps are not truly independent, and a good agent can notice and fix its own mistakes, which helps. But the shape is right: shorter paths, checkable steps and recoverable errors beat a smarter model on a longer path. This is why week 8 is about measuring, and why you should give the agent tools that verify (run the tests, re-read the file) and not only tools that act.
Common mistakes
- Dropping the assistant message from history, or rebuilding it from text only. Tool-use blocks must survive.
- Letting exceptions escape the tool call instead of returning them as errors.
- No step limit, no token budget, no timeout on the tool itself.
- Trusting the arguments: path traversal, huge outputs, shell strings. Validate every one.
- Printing nothing. Log each step's tool name, arguments and size of the result. You will need the trace in week 8.
Check yourself
- What does the loop send to the model on step 3 that it did not send on step 1?
- Why must
tool_resultblocks come before any text in the user message? - A tool raises
FileNotFoundError. What should the model see, and why does the wording of that message matter? - With $p = 0.97$ per step, how many steps until success drops below 50 percent?