Build an Agent Loop From Scratch in 50 Lines of Python

Tool use is a contract. You describe the operations available and the shape of their inputs; the model decides when to call them. When it wants one, the API response ends with stop_reason: "tool_use" and contains one or more tool_use blocks, each with an id, the tool name and an input object. The model has not run anything. Your application runs the tool and replies with a user message containing a tool_result block that names the same id.

The model has no memory between requests, so every request carries the whole conversation: the original task, every assistant turn and every tool result so far. The loop therefore has one data structure, the messages list, and one decision per iteration, made from stop_reason:

• tool_use: run the requested tools, append the results, call the API again.
• end_turn: the model has finished; return its text.
• Anything else: the response is incomplete or declined, so stop and handle it.

The Claude docs list the full process as five steps: send the tools and the user message, receive tool_use, execute each tool, send back the history plus the results, and repeat while stop_reason is tool_use. That is the entire mechanism. A ReAct agent, a coding agent and a research agent are all this loop with different tools, prompts and limits.

Here is the complete agent. It answers questions about the files in the directory where you run it, using two tools that can only read inside that directory:

1import pathlib, sys2import anthropic3 4client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY5MODEL = "claude-opus-5-5"6ROOT = pathlib.Path(".").resolve()7MAX_TURNS = 108 9PATH_ARG = {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}10TOOLS = [11    {"name": "list_files", "input_schema": PATH_ARG,12     "description": "List the entries of a directory, relative to the project root. Use '.' for the root."},13    {"name": "read_file", "input_schema": PATH_ARG,14     "description": "Return the text of one file, relative to the project root. Output stops at 20,000 characters."},15]16 17def safe_path(path):18    p = (ROOT / path).resolve()19    if not p.is_relative_to(ROOT):20        raise ValueError(f"{path} is outside the project root; use a relative path")21    return p22 23def run_tool(name, args):24    if name == "list_files":25        return "\n".join(sorted(p.name for p in safe_path(args["path"]).iterdir())) or "(empty)"26    if name == "read_file":27        return safe_path(args["path"]).read_text()[:20_000] or "(empty file)"28    raise ValueError(f"unknown tool: {name}")29 30def agent(task):31    messages = [{"role": "user", "content": task}]32    for _ in range(MAX_TURNS):33        resp = client.messages.create(model=MODEL, max_tokens=4096, tools=TOOLS, messages=messages)34        messages.append({"role": "assistant", "content": resp.content})35        if resp.stop_reason == "end_turn":36            return "".join(b.text for b in resp.content if b.type == "text")37        if resp.stop_reason != "tool_use":38            raise RuntimeError(f"stopped early: {resp.stop_reason}")39        results = []40        for block in resp.content:41            if block.type != "tool_use":42                continue43            try:44                out, failed = run_tool(block.name, block.input), False45            except Exception as e:46                out, failed = f"{type(e).__name__}: {e}", True47            results.append({"type": "tool_result", "tool_use_id": block.id, "content": out, "is_error": failed})48        messages.append({"role": "user", "content": results})49    raise RuntimeError(f"no final answer after {MAX_TURNS} turns")50 51if __name__ == "__main__":52    print(agent(" ".join(sys.argv[1:])))

Run it with ANTHROPIC_API_KEY set, from the root of a small project: python agent.py "What does this project do, and where is the entry point?". A typical run lists the root, reads a README or a manifest, opens one or two source files and answers, using three to five API calls.

It is roughly 50 lines: about 15 define the tools, 10 implement them and 20 are the loop. The next sections go through each part and the rule it follows. MODEL is a placeholder for whichever current Claude model you use; the loop does not depend on the model.

Each tool has three fields: a name, a description and an input_schema (a JSON Schema object). The model never sees your Python; it chooses tools and fills in arguments from these three fields alone. That makes the description the main way to steer it: say what the tool does, what each argument means, and any limit the model should know about. Both descriptions above say paths are relative to the project root, and read_file says output stops at 20,000 characters, so the model is not surprised by a truncated file.

The schema is a contract about shape, not a guarantee. By default the model usually fills the schema correctly but may not always; adding "strict": true to a tool definition makes the API constrain the input to match the schema exactly. Even with strict mode, the schema cannot express everything: "a path inside this directory" is a rule only your code can enforce, which is why safe_path resolves the path and rejects anything outside ROOT, including .. tricks and symlinks that point elsewhere.

Keep the tool set small and the tools distinct. Two tools that overlap (read_file and a cat shell tool) force the model to guess which one you meant. For more on naming, descriptions and versioning tool schemas, see Tool Calling Reliability Patterns.

The history must follow rules the API checks, and breaking them returns a 400 error:

• Results come immediately after the call. The user message with the tool_result blocks must directly follow the assistant message with the tool_use blocks. Nothing goes in between.
• Every tool_use gets a tool_result whose tool_use_id matches its id. Missing one produces the error "tool_use ids were found without tool_result blocks immediately after".
• Results go first. In that user message, all tool_result blocks come before any text you add.
• One message for all results. When the model calls several tools in one turn, send every result in a single user message. The parallel tool use docs warn that separate messages teach the model to stop making parallel calls.

The loop gets all four right by construction. It appends the assistant's whole content (text and tool_use blocks together), builds a results list with one entry per tool_use block, and appends that list as one user message. Parallel calls need no special code: the for loop over resp.content handles one call or five.

Append the content unchanged. If you turn on extended thinking, the assistant turn also contains thinking blocks, and the docs require you to pass them back complete and unmodified when you return tool results. Code that rebuilds the assistant message from only the text and tool calls breaks as soon as thinking is enabled.

stop_reason is in every successful response and tells you why the model stopped generating. A loop that only checks if stop_reason == "tool_use" and treats everything else as success will one day return half an answer. Each value needs a decision:

• end_turn: the model finished. Return the text.
• tool_use: run the tools and continue.
• max_tokens: the response hit your max_tokens cap. If the last block is a tool_use, it may be incomplete, and the docs say to retry with a higher limit rather than run it.
• refusal: the model declined. This is an HTTP 200, not an error; read stop_details, and the docs suggest retrying on a fallback model.
• pause_turn: a server-side tool loop hit its iteration limit. It only occurs with server tools; send the conversation back to continue.
• stop_sequence: one of your stop_sequences matched. It only occurs if you set them.
• model_context_window_exceeded: the response filled the context window; treat it as truncated.

The 50-line loop returns on end_turn, continues on tool_use and raises on everything else, carrying the reason in the message. That is the right default for a small agent: failing loudly is better than silently returning a truncated answer. A production loop would add specific handling where it pays off, such as retrying max_tokens with a larger cap or resending on pause_turn if you add server tools.

Nothing in the API stops a loop that never reaches end_turn. A model that keeps reading files or retries a failing tool can run until you notice the bill. MAX_TURNS caps the number of API calls per task, and when it is reached the loop raises instead of returning a guess.

Pick the limit from observed runs, not intuition: log how many turns real tasks take, and set the cap a little above the slowest successful run. Ten is generous for a two-tool read-only agent. An agent that edits code and runs tests may need more, and should probably also cap total tokens or wall-clock time. The usage field on every response reports input and output tokens, so a token budget is a running sum and a comparison.

The other guards are in the tools. safe_path means a confused or manipulated model cannot read /etc/passwd, and the 20,000-character cut stops one large file from filling the context window. Neither tool can write, so the worst case is a wrong answer, not damage. Once tools have side effects, a turn limit is not enough; you need permission checks or human approval before each risky call. For choosing limits and detecting stalls, see Autonomous Agent Stop Conditions.

There are two kinds of error, and they belong in different places.

Tool errors go back to the model. When run_tool raises (a missing file, a path outside the root, an unknown tool name), the loop catches the exception and returns its message in a tool_result with "is_error": true. The model reads it and adapts: it lists the directory to find the right path, or explains that it cannot access the file. The docs recommend instructive messages, saying what went wrong and what to try next, which is why the path error ends with "use a relative path". The Claude docs also note that when a tool request is invalid or missing parameters, Claude retries two to three times with corrections before apologising to the user, so a clear error usually leads to a corrected call.

API errors go to your code. Rate limits (429), server errors (5xx), timeouts and connection failures are raised by the SDK, not shown to the model. The Anthropic Python SDK retries 408, 409, 429 and 5xx responses and connection errors twice by default with backoff before raising; set max_retries on the client to change that. The loop lets those exceptions propagate, because the model cannot fix a rate limit.

The except Exception in the loop is deliberately broad, since any tool failure should become a result rather than crash the run. The boundary is that it also hides bugs in your own tool code from you, so log the exception before returning it in a real system.

The loop's structure carries over unchanged, but the wire format does not. Here is the same agent on the OpenAI Responses API, reusing TOOLS, MAX_TURNS and run_tool from the Claude version:

1import json, sys2from openai import OpenAI3from agent import TOOLS, MAX_TURNS, run_tool4 5oai = OpenAI()  # reads OPENAI_API_KEY6OAI_TOOLS = [{"type": "function", "name": t["name"], "description": t["description"],7              "parameters": t["input_schema"]} for t in TOOLS]8 9def agent_openai(task, model):10    items = [{"role": "user", "content": task}]11    for _ in range(MAX_TURNS):12        resp = oai.responses.create(model=model, tools=OAI_TOOLS, input=items)13        if resp.status != "completed":14            raise RuntimeError(f"stopped early: {resp.status} {resp.incomplete_details}")15        items += resp.output16        calls = [item for item in resp.output if item.type == "function_call"]17        if not calls:18            return resp.output_text19        for call in calls:20            try:21                out = run_tool(call.name, json.loads(call.arguments))22            except Exception as e:23                out = f"error: {type(e).__name__}: {e}"24            items.append({"type": "function_call_output", "call_id": call.call_id, "output": out})25    raise RuntimeError(f"no final answer after {MAX_TURNS} turns")26 27if __name__ == "__main__":28    print(agent_openai(" ".join(sys.argv[2:]), sys.argv[1]))

Three differences matter in practice. First, the Responses API has no stop_reason: the loop continues while the output contains function_call items and checks status for truncation. Second, arguments arrives as a JSON string, so json.loads can fail, and the loop catches that like any other tool error. Third, the Responses API has no error flag on results; the error is just text in output.

The Responses API can also keep the conversation on OpenAI's side with previous_response_id, in which case you send only the new function outputs each turn. Resending the full list, as here, keeps the code parallel to the Claude version and keeps the transcript in your hands. Pass the model name on the command line (python agent_openai.py <model> "question").

The 50-line loop covers what every agent needs. It leaves out the parts that become work as an agent grows:

• Context management: trimming, summarising or compacting a history that outgrows the context window.
• Streaming: showing text and tool calls as they are generated, and cancelling mid-run.
• Concurrency: running independent tool calls in parallel.
• Persistence: saving and resuming a run after a crash or across sessions.
• Approval and permissions: pausing before risky tool calls for a human or a policy check.
• Tracing: recording each turn, tool call and token count for debugging and evals.

Anthropic's SDKs include a beta Tool Runner (client.beta.messages.tool_runner in Python) that runs this loop for you from decorated functions, with a max_iterations limit. The docs suggest the manual loop when you need human approval, custom logging or conditional execution. The Claude Agent SDK goes further, with built-in file, shell and search tools, permissions, hooks, sessions and subagents. LangChain, LlamaIndex and the OpenAI Agents SDK each package the loop with their own abstractions.

Write the loop yourself first, even if you later replace it. When a framework agent misbehaves, the cause is nearly always in this loop: a dropped tool result, an unhandled stop reason, a tool error that became an exception, a history that grew too long. Knowing the loop tells you where to look. For a side-by-side of the frameworks, see LangChain vs LlamaIndex vs Agent SDK; for the Claude Agent SDK specifically, see Claude Agent SDK Guide.

Build the agent, then break each part to see the failure:

1. Run agent.py in a small project with a question that needs two or three files. 2. Print resp.stop_reason and the tool calls in each iteration to see the trace. 3. Set max_tokens=50 and ask for a long answer. The loop should raise stopped early: max_tokens rather than return a fragment. 4. Ask it to read ../../etc/passwd. The model should get an is_error result and explain that it cannot. 5. Set MAX_TURNS = 1 and ask a question that needs a file. The loop should raise after one call. 6. Comment out messages.append({"role": "user", "content": results}) and run it once. Read the 400 error: it names the tool_use ids that had no result. 7. Add a third tool, search(pattern), that greps the project, and check from the trace whether the model uses it instead of reading every file.

Pass criterion: you can explain each failure from the transcript alone, and the agent answers the original question correctly with the guards in place.