The Agent Loop

A warehouse manager asks an assistant which of two warehouses has more blue mugs. The assistant has one tool, stockLevel, and needs to call it twice, once per warehouse, then compare. On its first try it writes the warehouse name with a capital letter and gets an error back.

Whether this ends with the right answer, a crash, or a loop that never stops depends on about twenty lines of ordinary code around the model. That code is the agent loop, and this lesson writes it.

#The idea: four moves, repeated

What Is an Agent showed the loop as pseudocode. Written properly, every pass does four things:

1. Ask. Send the whole history to the model and get one reply.
2. Check. If the reply is a final answer, stop and return it.
3. Act. Otherwise the reply is a tool request. Run it. If it fails, turn the failure into an error message instead of crashing.
4. Record. Add the reply and the result to the history, so the next call can see them.

Around those four moves sits one more rule: a hard limit on the number of passes. A model can keep asking for tools forever, so the code, not the model, must have the last word on when to stop.

#One run, step by step

Here is the blue-mug question running through the loop. North has 140 mugs and south has 95. The model's replies are realistic but scripted, so you can follow exactly what the code does with each one.

history = [goal]for step in 1..maxSteps:  reply = model(history)  history += reply  if reply is an answer: return it  try: result = run the tool  except: result = the error message  history += resultreturn "stopped: step limit"

#The loop in code

The model argument is any function that takes the history and returns either { type: "answer", text } or { type: "tool", tool, input }. In a real app it wraps a call to a model API and converts the reply into one of those two shapes. Here it is a stand-in, so the code runs without one.

function runAgent(model, tools, goal, maxSteps = 10) {
  const history = [{ role: "user", text: goal }];
  for (let step = 1; step <= maxSteps; step++) {
    const reply = model(history);
    history.push(reply);
    if (reply.type === "answer") {
      return { answer: reply.text, steps: step, stopped: "answered" };
    }
    let result;
    try {
      const tool = tools[reply.tool];
      if (!tool) throw new Error(`No tool named ${reply.tool}`);
      result = tool(reply.input);
    } catch (err) {
      result = { error: err.message }; // the model reads errors too
    }
    history.push({ role: "tool", result });
  }
  return { answer: null, steps: maxSteps, stopped: "step limit" };
}

def run_agent(model, tools, goal, max_steps=10):
    history = [{"role": "user", "text": goal}]
    for step in range(1, max_steps + 1):
        reply = model(history)
        history.append(reply)
        if reply["type"] == "answer":
            return {"answer": reply["text"], "steps": step, "stopped": "answered"}
        try:
            tool = tools.get(reply["tool"])
            if tool is None:
                raise ValueError(f"No tool named {reply['tool']}")
            result = tool(**reply["input"])
        except Exception as err:
            result = {"error": str(err)}  # the model reads errors too
        history.append({"role": "tool", "result": result})
    return {"answer": None, "steps": max_steps, "stopped": "step limit"}

And the run from the tracer, with a fake tool and a scripted model that returns one reply per pass:

const stock = { north: 140, south: 95 };
const tools = {
  stockLevel: ({ warehouse }) => {
    if (!(warehouse in stock)) {
      throw new Error(`Unknown warehouse "${warehouse}". Use "north" or "south".`);
    }
    return { warehouse, blueMugs: stock[warehouse] };
  },
};
const script = [
  { type: "tool", tool: "stockLevel", input: { warehouse: "North" } },
  { type: "tool", tool: "stockLevel", input: { warehouse: "north" } },
  { type: "tool", tool: "stockLevel", input: { warehouse: "south" } },
  { type: "answer", text: "North has more blue mugs: 140 against 95." },
];
const fakeModel = (history) => script[(history.length - 1) / 2];
 
console.log(runAgent(fakeModel, tools, "Which warehouse has more blue mugs?"));
// { answer: 'North has more blue mugs: 140 against 95.', steps: 4, stopped: 'answered' }
console.log(runAgent(fakeModel, tools, "Which warehouse has more blue mugs?", 2));
// { answer: null, steps: 2, stopped: 'step limit' }

stock = {"north": 140, "south": 95}
 
def stock_level(warehouse):
    if warehouse not in stock:
        raise ValueError(f'Unknown warehouse "{warehouse}". Use "north" or "south".')
    return {"warehouse": warehouse, "blue_mugs": stock[warehouse]}
 
tools = {"stock_level": stock_level}
script = [
    {"type": "tool", "tool": "stock_level", "input": {"warehouse": "North"}},
    {"type": "tool", "tool": "stock_level", "input": {"warehouse": "north"}},
    {"type": "tool", "tool": "stock_level", "input": {"warehouse": "south"}},
    {"type": "answer", "text": "North has more blue mugs: 140 against 95."},
]
fake_model = lambda history: script[(len(history) - 1) // 2]
 
print(run_agent(fake_model, tools, "Which warehouse has more blue mugs?"))
# {'answer': 'North has more blue mugs: 140 against 95.', 'steps': 4, 'stopped': 'answered'}
print(run_agent(fake_model, tools, "Which warehouse has more blue mugs?", max_steps=2))
# {'answer': None, 'steps': 2, 'stopped': 'step limit'}

Swap fakeModel for a real model call and tools for real ones, and the loop itself does not change. Real frameworks add streaming, logging and several tool calls per reply, but the core is this loop.

#Good reasons to stop

An answer is the stop you want. The others are safety nets, and the loop should return which one fired, so the caller never mistakes a cut-off run for a finished one.

• Step limit. The one shown above. Pick it from real runs: if a task normally takes 5 steps, a limit of 15 leaves room without allowing endless wandering.
• Budget or time. Stop when total tokens or seconds pass a limit, for the same reason.
• Repeats. If the model asks for the exact same tool with the exact same input it already tried, it is probably stuck. Keep a set of past requests, and on a repeat either stop or add a note to the history: "You already tried this. Try something different or answer with what you have."
• A person says stop. Long runs should be cancellable.

#What each step costs

The number of model calls grows in a straight line with the number of steps. The amount of text the model reads does not. Every call re-reads the whole history, and the history gets longer every step.

Say each step adds about 500 tokens to the history. Then call 1 reads about 500, call 2 about 1,000, and call 20 about 10,000. Over 20 calls that is 500 × (1 + 2 + … + 20) = 500 × 210 = 105,000 tokens read, for a history that ends only about 10,000 tokens long.

That is why long runs get slow and expensive faster than you expect, and why short tool results matter so much. Many systems cut the cost by caching the unchanged start of the history, or by replacing old steps with a short summary. A summary can drop a detail the agent needs later, so it is a trade-off. Long histories also hurt the quality of answers: see Context Rot.

#Try it yourself

#Common mistakes

#Check yourself

#What to practise next

Copy the loop, write a scripted model that asks for the same tool twice with the same input, and add the repeat check. Then continue with Planning and Multi-Agent Systems, for tasks too big for one loop to keep in its head.