Build the agent loop from scratch in Python

Video lecture

Build the agent loop from scratch in Python

14 chapters · about 9 min · full transcript

Coming soon

Chapter 1 of 14

Build the agent loop from scratch

The anatomy of a tool call
A production-minded loop
Budgets, errors and logs

The narrated lecture is in production

Every chapter is scripted and ready. Browse the chapters and read the full transcript now — the video will appear here when it’s published.

Chapters

Transcript of the narration, chapter by chapter.

0:00 Build the agent loop from scratch

Every agent framework you'll ever use hides the same forty lines of code. If you've written those lines yourself, debugging any framework becomes easy. In this lesson you'll build the agent loop from scratch in Python, with the production habits that most tutorials skip.

0:19 Why build it yourself?

Why build the loop yourself when frameworks exist? Because when something breaks at two in the morning, you need to know what's actually happening. Think of learning to drive a manual car before an automatic. You may never drive stick again, but you'll understand what the gearbox is doing. Every framework, whether it's an SDK tool runner, LangGraph or the Claude Agent SDK, runs this same cycle underneath. Once you've written it, framework docs stop being magic and start being a list of conveniences, and debugging becomes reading a transcript instead of guessing.

0:59 Anatomy of a tool call

Start with the anatomy of a tool call. You send the model your messages, a system prompt, and a list of tools. Each tool has a name, a description and a JSON schema for its inputs. If the model wants a tool, the stop reason is tool use, and the content contains tool use blocks, each with an id, a name and input arguments. Your code runs the tool, then sends back tool result blocks that point to those ids. Then you call the model again.

1:36 Two rules

Two rules trip people up. First, append the assistant's whole content to the history, not just the text. It can include thinking blocks and several tool calls. Second, when the model asks for multiple tools at once, return all the results together in one user message. Split them up and the model learns to stop calling tools in parallel, which slows everything down.

2:03 Handle every stop reason

Now the stop reasons. End turn means the model is done. Tool use means run tools and loop. Max tokens means the output was cut off, so continue or raise the limit. Pause turn appears with long server side tools, and you just send the conversation back. And on some newer models, refusal means the model declined, so don't try to read tool calls from that response. Handle each one explicitly and your loop never gets stuck.

2:36 Simple trace: umbrella question

Let's trace a simple example first, before the business one. You give the agent one tool, get weather, and ask: should I take an umbrella in Manchester tomorrow? Call one: the model replies with stop reason tool use and a tool block asking for get weather with city Manchester. Your code runs the function and gets back, rain likely, eighty percent. You append the assistant's content, then a user message with the tool result pointing to that block's id. Call two: the model replies with end turn: yes, take an umbrella. Two calls, one tool. That's the whole machine.

3:19 Production habits

Let's talk production habits. Errors: if a tool fails, return the error message with is error set to true. The model often fixes its own mistake, like a malformed id. Size: cap tool outputs, because a two hundred kilobyte JSON blob will swamp the context and your bill. Budgets: always set a maximum number of steps, and in production add a token or cost budget. Logs: record the stop reason, tokens, latency and tool names for every step.

3:53 Worked trace

Here's a worked trace. The goal: prepare me for a call with Acme tomorrow. Step zero, the model searches the CRM for Acme and finds Sara Khan, Head of Growth. Step one, it fetches her open deals: a twelve thousand pound proposal waiting on a pricing call. Step two, it ends the turn with three crisp bullets. Three model calls, two tool calls. If your logs show twelve calls for a goal like this, that's a signal: vague tool descriptions, missing data, or no clear finish line.

4:31 Cost grows with steps

One cost insight before we finish. Every step resends the entire conversation, so input tokens pile up with each loop. That's why long agent runs get expensive fast, and why later lessons cover prompt caching and context trimming. Once you understand the manual loop, you can use helpers like the Anthropic tool runner, the Claude Agent SDK, or other frameworks, knowing exactly what they're doing for you.

5:00 Errors: fragile vs robust

Let's zoom in on the error handling, because it's where amateur loops and professional loops really differ. Picture a tool that looks up an order, and the model passes an order number with a typo. A fragile loop throws an exception and the whole run dies, wasting every token spent so far. A robust loop catches the exception and returns a short, specific message: order not found, ids look like O R D dash five digits. Nine times out of ten, the model reads that, fixes the argument and carries on. Also separate two kinds of failure. Rate limits and server errors are retryable, and the official SDKs already retry them with backoff. Bad requests, like an invalid schema, are not retryable. Fix the request instead of hammering the API.

5:57 Deeper: the ambiguous-account bug

Let's deepen the CRM briefing example. Imagine the same agent at a Karachi software reseller with two thousand CRM contacts. On a normal day, briefing requests take three model calls and two tool calls, as we saw. But when a company name matches several records, like two different Acme entities, the first version of the agent picked the first match and briefed the salesperson on the wrong account. The fix was not a smarter model. The team changed search CRM to return a city and industry with each match, and added one sentence to the system prompt: if more than one company matches, ask which one. Wrong account briefings dropped to almost zero, at the cost of an occasional clarifying question, which salespeople actually liked.

6:51 Watch me do it: run_agent()

Watch me do it. Let's run the loop from the lesson and follow it line by line. First, the tools list: search CRM and get deals, each with a description and a strict input schema. Next, run tool looks up the function in the registry, calls it, caps the output at eight thousand characters, and turns any exception into an error string with is error true. Now run agent. It starts the messages with the goal, then loops up to ten steps. Each step calls messages create with the system prompt, tools and messages, and logs the step number, stop reason, tokens and time. It appends the whole assistant content. If the stop reason is end turn, it returns the text. If it's max tokens, it asks the model to continue concisely. Otherwise, for every tool use block, it runs the tool and collects a tool result with the matching id, then appends all results in one user message. When I run it, the log shows three steps: tool use, tool use, end turn.

8:07 Try this now

Here's your try this now. Copy the loop from the lesson text and replace the two CRM functions with a stub of one tool you actually use, even if it just returns fake data. Run five different goals. For each, write down the number of steps, total input and output tokens, and seconds taken. Then deliberately break the tool: make it throw an error and watch whether the model recovers when it sees the error message. That ten minute experiment teaches you more about agent behavior than any diagram.

8:46 Recap

To recap: the loop is call, run tools, append results, repeat. Append full content, return results together, send errors back as data, cap everything, and log every step. Your next step: run the lesson's code against a stub of one of your own tools, try five goals, and record the steps, tokens and latency. That's your baseline for every improvement to come.

Why build it by hand first

Frameworks and SDK helpers are great, but if you have never written the loop yourself you will struggle to debug them. The raw loop is about 40 lines. Once you understand it, every framework is just conveniences around it.

The anatomy of a tool call (Claude Messages API)

You send messages, a system prompt and a list of tools, each with a name, description and JSON Schema input_schema.
The model replies. If it wants a tool, stop_reason is "tool_use" and the content contains one or more tool_use blocks with an id, name and input.
You append the assistant's full content (not just its text) to messages, run each tool, then append one user message containing a tool_result block per call, each referencing the matching tool_use_id.
Call the API again. Repeat until stop_reason is "end_turn" (or something else you must handle).

Other stop reasons to handle: "max_tokens" (output was cut off; raise the limit or ask it to continue), "pause_turn" (a long server-side tool turn paused; send the conversation back to continue), and "refusal" on some newer models (the model declined; do not read tool calls from it). OpenAI's Responses API and Google's Gemini API follow the same idea with different field names, which the platform-integration course compares side by side.

Hands-on: a minimal but production-minded loop

import os, json, time, logging
import anthropic

logging.basicConfig(level=logging.INFO)
log = logging.getLogger("agent")
client = anthropic.Anthropic()  # ANTHROPIC_API_KEY from env; SDK retries 429/5xx by default
MODEL = os.environ.get("AGENT_MODEL", "claude-sonnet-5")  # verify current IDs in the docs

TOOLS = [
    {
        "name": "search_crm",
        "description": "Search CRM contacts by company name. Returns up to 5 matches with id, name, role, last_contacted.",
        "input_schema": {
            "type": "object",
            "properties": {"company": {"type": "string", "description": "Company name, e.g. 'Acme Ltd'"}},
            "required": ["company"],
            "additionalProperties": False,
        },
    },
    {
        "name": "get_deals",
        "description": "List open deals for a CRM contact id. Returns stage, value and next step.",
        "input_schema": {
            "type": "object",
            "properties": {"contact_id": {"type": "string"}},
            "required": ["contact_id"],
            "additionalProperties": False,
        },
    },
]

def search_crm(company: str) -> list[dict]:        # replace with your real CRM client
    return [{"id": "c_101", "name": "Sara Khan", "role": "Head of Growth", "last_contacted": "2026-08-30"}]

def get_deals(contact_id: str) -> list[dict]:
    return [{"stage": "proposal", "value_gbp": 12000, "next_step": "pricing call"}]

REGISTRY = {"search_crm": search_crm, "get_deals": get_deals}

def run_tool(name: str, args: dict) -> tuple[str, bool]:
    fn = REGISTRY.get(name)
    if fn is None:
        return f"Unknown tool {name}", True
    try:
        return json.dumps(fn(**args))[:8000], False   # cap tool output size
    except Exception as exc:                          # return errors to the model, don't crash
        return f"Tool error: {type(exc).__name__}: {exc}", True

def run_agent(goal: str, max_steps: int = 10) -> str:
    messages = [{"role": "user", "content": goal}]
    system = ("You are a sales-ops assistant. Use tools to gather facts before answering. "
              "If data is missing, say so. Finish with a 3-bullet briefing.")
    for step in range(max_steps):
        t0 = time.time()
        resp = client.messages.create(model=MODEL, max_tokens=4000, system=system,
                                      tools=TOOLS, messages=messages)
        log.info("step=%d stop=%s in=%d out=%d %.1fs", step, resp.stop_reason,
                 resp.usage.input_tokens, resp.usage.output_tokens, time.time() - t0)
        messages.append({"role": "assistant", "content": resp.content})
        if resp.stop_reason == "end_turn":
            return "".join(b.text for b in resp.content if b.type == "text")
        if resp.stop_reason == "max_tokens":
            messages.append({"role": "user", "content": "Continue, and be concise."})
            continue
        if resp.stop_reason != "tool_use":
            return f"Stopped: {resp.stop_reason}"
        results = []
        for block in resp.content:
            if block.type == "tool_use":
                output, is_error = run_tool(block.name, block.input)
                log.info("tool=%s args=%s error=%s", block.name, block.input, is_error)
                results.append({"type": "tool_result", "tool_use_id": block.id,
                                "content": output, "is_error": is_error})
        messages.append({"role": "user", "content": results})  # all results in ONE message
    return "Stopped: step budget exhausted"

if __name__ == "__main__":
    print(run_agent("Prepare me for a call with Acme Ltd tomorrow."))

Line-by-line: the parts that matter

Append the whole resp.content. It may include thinking blocks and multiple tool calls; dropping them breaks the conversation.
All tool results in one user message. Models can request several tools in parallel; splitting results across messages degrades that behavior.
Errors go back as is_error: true. The model can often recover (fix an argument, try another tool). Crashing the loop wastes the run.
Output caps. A tool that returns 200 KB of JSON will blow your context and your bill.
A step budget. Always. Pair it with a token or cost budget in production.
Structured logs per step. Stop reason, tokens, latency and tool names are the minimum trace you need (module 5 upgrades this to proper tracing).

Beyond the manual loop

The Anthropic SDKs include a beta tool runner (client.beta.messages.tool_runner in Python with the @beta_tool decorator) that runs this loop for you while still letting you inspect each turn. The Claude Agent SDK goes further, packaging Claude Code's harness (file, shell, web tools, hooks, sub-agents) as a library. Other ecosystems have equivalents: OpenAI's Agents SDK Runner, LangGraph's prebuilt agents, Google's ADK. Use them once you understand what they do for you.

Worked example trace

Goal: "Prepare me for a call with Acme Ltd tomorrow."

Step 0: model calls search_crm(company="Acme Ltd").
Step 1: sees Sara Khan, calls get_deals(contact_id="c_101").
Step 2: end_turn with three bullets: who Sara is, the open £12,000 proposal, and a suggested agenda around the pricing call.

Three model calls, two tool calls. If your logs show twelve calls for this goal, something is wrong: vague tool descriptions, missing data, or instructions that never say when to stop.

Pitfalls

Parsing tool arguments with string matching instead of using the parsed input object.
Retrying non-retryable errors (400s) forever; let the SDK retry 429/5xx and fix the request for 4xx.
Letting tools raise exceptions that kill the process.
Forgetting that each loop iteration resends the entire history (costs grow roughly quadratically with steps unless you cache and trim).

Measuring success

For a fixed set of 20 goals, record: completion rate, average steps, average tool errors, tokens and cost per goal. These baseline numbers are what every later improvement is measured against.

The loop: call the model, run requested tools, append results, repeat until end_turn or a budget stops it.
Append the assistant's full content and return all tool results in a single user message.
Return tool failures as is_error results so the model can recover instead of crashing.
Cap steps, tool output size and cost from the first version.
Log stop reason, tokens, latency and tool names for every step.

Run the loop in this lesson against a stub of one of your own tools. Record steps, tokens and latency for five goals and note one improvement.

Enrol for free to save your progress

Reading is always free. Enrol to keep your place, take the final assessment and earn a verifiable certificate.

Build the agent loop from scratch in Python