The agentic loop: how an AI agent works, step by step, and how it should stop
An agentic loop is the cycle every AI agent runs: send the conversation to the model, let it ask for a tool, run the tool, add the result to the conversation, and call the model again, until the model answers without asking for a tool. With Claude, stop_reason tells you which case you are in: tool_use means keep going, end_turn means done.
What is an agentic loop?
An agentic loop is the cycle at the heart of every AI agent. The Claude Agent SDK docs describe it plainly: Claude evaluates your prompt, calls tools to take action, receives the results, and repeats until the task is complete.
What makes it agentic is who decides the next step. In a scripted workflow your code says "first look up the customer, then the booking". In an agentic loop the model chooses each step from what it has learned so far, which is why the same agent can handle questions nobody scripted.
The agentic loop, step by step
With the Claude API, one loop looks like this:
- Send the conversation, the tool definitions and the system prompt.
- Read
stop_reason. If it istool_use, the response contains one or moretool_useblocks. - Run each requested tool in your code.
- Append Claude's message and a user message with your
tool_resultblocks to the history. - Call again with the longer history, and go back to step 2.
- Finish when
stop_reasonisend_turn: the last message is the answer.
python
while True:
response = client.messages.create(model=MODEL, max_tokens=2048,
system=SYSTEM, tools=TOOLS, messages=messages)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
break # end_turn (or a case you handle below)
results = [{"type": "tool_result", "tool_use_id": b.id, "content": run_tool(b.name, b.input)}
for b in response.content if b.type == "tool_use"]
messages.append({"role": "user", "content": results})
The appended tool results are what let the model reason about its next move. Each pass of steps 2 to 5 is one turn.
An example: "Where's my deposit?"
A bike-rental support agent gets: "I returned my bike yesterday. Where's my deposit?"
| Turn | Claude asks for | The tool returns |
|---|---|---|
| 1 | find_customer with the email |
Verified customer, ID C-2081 |
| 2 | lookup_booking for the latest booking |
Bike back undamaged, $50 deposit still held |
| 3 | issue_refund for $50 |
Refund confirmed |
| 4 | Nothing: end_turn |
"Your $50 deposit is on its way back to your card." |
Nobody wrote "call these three tools in this order". Claude chose each one from the previous result.
How an agentic loop should stop
The stop signal is stop_reason, not the text. tool_use means continue; end_turn means done. Handle the others too: max_tokens (the reply was cut off), pause_turn (a server tool paused; send the content back to continue), refusal, and a safe default for values you don't handle yet.
Three wrong ways to stop an agent loop
The Claude Certified Architect exam guide names these anti-patterns in task statement 1.1:
- Parsing the text. Stopping when Claude writes "I'm done" or "Here is your answer". Natural language is not a reliable signal.
- Using an iteration cap as the main stop. A fixed "stop after 5 rounds" cuts off tasks that needed 6 and wastes nothing on tasks that needed 2.
- Treating any text as completion. Claude often writes a sentence and asks for a tool in the same response; text present does not mean the work is finished.
A cap still belongs in production code, as a safety guard: Anthropic's own agent guidance recommends a maximum number of iterations to catch runaway loops. The cap protects you; stop_reason tells you the job is done.
Who runs the loop: API, Agent SDK or Claude Code
| Who writes the loop | How you limit it | |
|---|---|---|
| Messages API | You | Your own counters and checks |
| Claude Agent SDK | The SDK | max_turns, max_budget_usd, hooks |
| Claude Code | Claude Code | Permission modes, hooks, settings |
The SDK's ResultMessage reports how the loop ended (success, error_max_turns, error_max_budget_usd), so even a capped run tells you what happened. Choosing between these is the subject of the API vs Agent SDK vs Claude Code comparison.
The agentic loop on the Claude Certified Architect exam
Task statement 1.1, the first of Domain 1 (27% of the CCAR-F exam), is exactly this loop: continue on tool_use, terminate on end_turn, append tool results between iterations, and the difference between model-driven decisions and pre-configured sequences. Expect a question where a loop stops too early or runs forever; the fix is almost always to drive it from stop_reason.
More in all articles.
Sources: How the agent loop works (Agent SDK); Tool use with Claude; Handling stop reasons; Building effective agents; Claude Certified Architect Foundations exam guide v1.0, task statement 1.1.
FAQ
What is an agentic loop?
The cycle an AI agent repeats to finish a task: the model decides the next step, usually a tool call; the tool runs; its result goes back into the conversation; the model decides again, until it gives a final answer.
How does an agentic loop know when to stop?
With Claude, from the response's stop_reason: tool_use means run the requested tools and continue; end_turn means Claude finished. A turn or budget cap is a safety guard, not the main stop signal.
What is the difference between an agentic loop and a workflow?
In a workflow, your code decides the sequence of steps in advance. In an agentic loop, the model decides the next step at each turn, based on what the last tool returned.
Do I have to write the agentic loop myself?
With the Messages API, yes. The Claude Agent SDK and Claude Code run it for you, with limits such as max turns and a spend budget.