The agent loop

An agent looks like one thing running continuously. It is not. It is a loop you wrote, calling a model that makes one stateless decision each time round and then stops. Understanding what the loop does, and what tells it to end, is what makes the rest of agent design make sense.

Common questions

1. Whose loop is it?
   The loop is your code, not the model's. On each pass you send the whole messages array and Claude makes one stateless decision from it: either a final answer or a request for a tool. It never runs the tool and it never loops.
2. What happens on a pass that asks for a tool?
   You run the tool yourself, append the result to the messages and send the whole thing again. Claude asking for a tool is a request handed back to your code, not something it goes off and does.
3. Why does the tool result have to be appended?
   Because nothing is remembered between calls. The messages array is the memory, and each call the model reads the whole thing cold, including its own tool request from the turn before.
4. What if I do not append it?
   The model has no way of knowing the tool ever ran, so it will just ask again, quite reasonably, because from where it sits nothing happened.
5. How does the loop know when to stop?
   The stop is structural, read from the stop reason on the response, never from the model's prose. The API puts the stop reason on the wire for you to read, which makes it an actual signal.
6. Is the stop reason just done or not done?
   No, the stop reason is not a boolean. The flow branches on more than two values, so you have to check all of them rather than the two you expected.
7. Which values catch people out?
   A truncated response, a paused turn and a filled context window all mean not done, and none of them look any different from done unless you check for them. The branch you did not handle is the bug.
8. Why not just read the text to see if it finished?
   The prose is not a signal at all, it is a sentence you have decided to read as one. Matching on it gives false positives when it says it is done and is not, and false negatives when it is done and never says so.
9. There is text in the response. Does that mean it finished?
   No. Every call returns a response and nearly all of them have text, so text being present says nothing about whether the work is done. The model can say what it is about to do and call the tool in the same turn.
10. Is an iteration cap a reasonable way to stop?
    A cap is a backstop and not the thing you stop on, because the real stop is the structural end of turn. Reaching the cap only means the cap was reached, and that has to be carried out of the loop as its own fact.
11. What goes wrong if the cap is the stop?
    A stump comes back looking exactly like a finished answer. The cap also cannot make the model settle faster, because the model cannot see it, so it just gets cut off part way.
12. What if it is iterating more than it needs to?
    The lever is a budget it can actually see, or less effort per turn. A cap is only there for when those have already failed.

Back to For developers. The craft around it is Working with AI.