011 min
The problem the agent loop solves
A developer asks a language model to fix three failing tests in a file called auth.ts. A language model is a program trained on large amounts of text to predict what comes next. Asked once, it answers once. It has not run the tests, so it cannot see which three fail or why. It writes a likely fix from the file it was given, and nobody knows whether the fix works until a person runs the tests.
That gap is the problem. One model call produces one answer and ends. The model cannot try something, look at the result and change its mind. Before agents, people filled the gap by hand. They pasted the error message back into the chat, asked again, and repeated. Every round needed a person.
The cycle that takes the person out of those rounds is the agent loop. A program calls the model, runs what the model asks for, shows the model what happened, and calls it again. The model in this role is the core of an AI agent. The rest of this article follows the auth.ts task through that cycle.
022 min
How the agent loop works
Each pass through the cycle is called a turn. A turn has three parts.
- Decide. The program sends the model its context. The context is everything the model can see in this task: the goal, the instructions, the descriptions of the available tools, and every earlier result. The model replies with text, with a request to use a tool, or with both.
- Act. A tool is an ordinary function the program offers, such as running a shell command or reading a file. The model does not run it. It writes a structured request, and the program runs the function. This exchange is called tool use. A model can ask for more than one tool in the same turn.
- Observe. The program adds the tool's output to the context. This output is the observation.
Then the cycle starts again, and the model decides with one more result in view. The step where the interesting thing happens is that decision after each observation. No developer wrote in advance what the model does next. The result decides.
Anthropic's guide to building agents, published in December 2024, calls an agent a model that uses tools and reads feedback from its environment, again and again. The loop ends when the model replies with no tool request. That reply is the final answer.
The model keeps no memory between turns. The program sends the whole history again each time, so the history is the only memory the loop has.
031 min
A four-turn trace: fixing the failing tests
Anthropic's Claude Agent SDK documentation walks through a session of this kind that takes four turns: three that call tools and a last one that only writes text.
Take the auth.ts task turn by turn.
- Turn 1. The model asks to run the test command. The output shows three failures.
- Turn 2. The model asks to read auth.ts and the test file. The program returns both files.
- Turn 3. The model asks to edit auth.ts and then run the tests again. All three tests pass.
- Final turn. The model replies with text only: the bug is fixed and the tests pass. There is no tool request, so the loop ends.
Notice what each observation changed. The test output in turn 1 told the model which files to read. The test output in turn 3 told it that it could stop. A single call would have had neither piece of information.
042 min
Where the agent loop came from
Before 2022, researchers studied two skills apart. Reasoning meant writing out steps of thought before answering, as in chain-of-thought prompting. Acting meant producing a plan of actions. Shunyu Yao and colleagues joined them in a 2022 paper called ReAct. The model writes a short thought, then an action, reads the result, and writes the next thought. Many agent loops since then follow this pattern, with or without the visible thoughts.
What ReAct measured
On ALFWorld and WebShop, ReAct beat imitation learning and reinforcement learning methods by 34 and 10 percentage points of absolute success rate, using only one or two worked examples in the prompt.
The ReAct authors argue that the written reasoning helps the model form a plan, follow it and adjust it when something goes wrong, while the actions let it collect facts from outside.
Why thinking alone was not enough
On question-answering tests, ReAct reduced the made-up facts and the carried-forward mistakes that came with chain-of-thought alone, because it looked facts up in a Wikipedia interface. A model that only reasons has nothing to check its reasoning against. A model in a loop can look the fact up, and the loop shows it what it found.
What Reflexion added
A year later, Noah Shinn and colleagues added memory across attempts. A Reflexion agent finishes a try, writes a short note about what went wrong, and reads that note on the next try. The note is plain text kept in memory. The model itself is not retrained.
On the HumanEval coding benchmark, Reflexion reached 91 percent pass@1 in 2023, where the earlier best result from GPT-4 was 80 percent. Pass@1 is the share of problems whose first submitted solution passes the hidden tests.
What SWE-agent measured
In the 2024 SWE-agent paper, an agent that ran commands and read their output solved 12.5 percent of SWE-bench tasks on its first attempt, far above earlier systems that never saw their own results. The authors also argue that the tools an agent is given matter as much as the model. A command whose output is short and clear helps the loop more than one that prints pages of text.
051 min
Why the agent loop depends on what it observes
The loop is only as reliable as its observations. An observation can be a test result, a file, a search result or an error message. The model chooses its next move from these, so a vague or misleading observation sends it the wrong way.
Anthropic makes the same point. Its guide says an agent should get real results from its environment on every step, such as a tool's output or the outcome of running code, so it can judge how far along it is.
This explains why coding agents work well in loops. A test run gives a clear yes or no after each change. A task with no such check, such as "make this page feel friendlier", gives the loop nothing to measure, and the model must guess when it is done.
Good tools return short, specific results. A command that fails should say what failed. A search that finds nothing should say it found nothing. A tool that returns an empty string leaves the model to guess.
061 min
How an agent loop stops
A loop that stops only when the model says so will sometimes never stop. The model may keep trying a fix that cannot work. So builders add limits from outside the model.
- A turn cap. The loop ends after a fixed number of turns. The AI SDK for TypeScript stops an agent after 20 steps unless the developer sets another limit, so that a stuck agent does not make excessive calls and costs.
- A spending cap. The loop ends when the cost of the model calls reaches a set amount.
- A time limit. The loop ends after a fixed time, which protects against a tool that hangs.
- A human gate. Some tool calls, such as deleting files or sending money, wait for a person to approve them.
A cap is not a finish line. A loop that ends at a cap has stopped, not finished. The program should say so, return the partial work and the reason, and keep the history so a person can resume or change the task. Reporting a capped run as a success is a bug in the program that wraps the loop.
Choose the cap from real runs. If most tasks finish in ten turns, a cap of 20 leaves room for hard cases. A cap of 200 mostly pays for the cases that were never going to finish.
072 min
What the agent loop does to the context window
The context grows on every turn. Each turn sends the instructions, the tool descriptions and the full history, plus the newest tool output. A large file or a long command output adds many tokens in one turn. A token is a small piece of text, often a short word or part of a word. Each turn therefore sends more text than the one before, so the cost of a turn tends to rise as the task goes on.
The context window is the most text the model can read at one time. When the history nears that limit, the program must shorten it. The usual method is compaction, which replaces old messages with a summary.
What compaction can lose
In the Claude Agent SDK, compaction swaps old messages for a summary, so an instruction given early in a session may not survive it. Rules that must last the whole task belong in text the program sends again on every turn, such as the system instructions, and not only in the first message.
Why long histories hurt even before the limit
The limit is not the only problem. In 2023, Nelson Liu and colleagues found that language models answer best when the needed fact sits at the start or the end of a long input, and worse when it sits in the middle. In a long loop, the early observation that mattered most can end up in the middle of the history. Shorter histories, made by clearing old tool outputs or by handing a subtask to a helper agent with a fresh context, keep the important facts near the ends.
082 min
How agent loops fail
Four failures are common. Each one has a tell that shows up in the log of turns.
Repeating the same action
The model calls the same tool with the same arguments, gets the same result, and calls it again. The tell is a run of identical tool calls and a token count that rises while nothing changes.
A July 2026 study by Xinyi Hou and colleagues scanned 6,549 repositories of LLM agents and confirmed 68 infinite-loop failures across 47 projects. The authors define the failure as a loop whose feedback path has no bound. That gap lets one request run up cost and context, and repeat side effects such as sending the same message many times.
Looping between agents
The repeat does not need a tool call. The same study counts repeated handoffs, where one agent passes work to another and the work comes straight back. In a system with several agents, count the passes between them as well as the turns of each.
The fix for both is the same. Record each call with its arguments, flag a repeat, and end the run or change the instruction after a set number of repeats.
Mistakes that multiply
Suppose each step is right 90 percent of the time. This is an illustrative number, not a measurement. The chance that ten steps in a row are all right is 0.9 multiplied by itself ten times, about 35 percent. Long loops fail more often than their single steps suggest, which is why each step needs a check, such as a test run.
Declaring success too early
The model replies with no tool request while the task is unfinished, or after a check that proved nothing. A coding agent can report that the fix is done without having run the tests. The fix is to state what done means in checkable terms, such as "the test command exits with no failures", and to have the program run that check itself.
091 min
The agent loop vs. nearby concepts
The deciding fact is who chooses the next step. In an agent loop the model chooses. In a fixed chain of calls, the developer's code chooses.
| Concept | Who picks the next step | Number of steps |
|---|---|---|
| A single model call | Nobody, there is one step | 1 |
| Prompt chaining | The developer's code, in a fixed order | Fixed in advance |
| Agent loop | The model, after each observation | Not known in advance |
| ReAct | A prompting pattern for what the model writes inside each turn | Not applicable |
Teams often call the same system an agentic workflow. Ask the deciding question. If the code fixes the order of steps, the system is a workflow. If the model picks each step from the last result, the system has an agent loop.
ReAct is not a competitor to the loop. It describes the text the model writes in each turn, and the loop is the program that repeats the turns.
The answer is sometimes both. A workflow can run in a fixed order and hand one open-ended step, such as fixing a failing test, to an agent loop with its own caps.
101 min
What the agent loop means for your work
Each role makes a different decision about the loop.
- Engineers set the caps and log every turn with its tool name and arguments. Without that log, a repeated action is invisible. They also decide what each tool returns when it fails, since the model reads that text.
- Product managers decide what happens when a run hits a cap. Ending at a cap means the task is unfinished, so the product needs a message and a way to resume. They also set a spending limit per task.
- Designers decide what the user sees across dozens of turns, and where an approval prompt appears. A user watching a long loop needs to know what the agent is doing and how to stop it.
- Founders price tasks by the spread of turns, not the average. A task that takes 30 turns costs far more than one that takes 3, and the number of turns is not known in advance.
For a task whose steps are known in advance, a fixed chain is simpler and cheaper to test. A loop earns its place when the next step depends on what the last one returned.
?5 questions
Questions people ask
Is ReAct the same as an agent loop?
How many turns does an agent loop usually take?
Does the model remember earlier turns by itself?
Can an agent loop run without a person watching?
What happens when the loop hits its turn cap?
▶3 videos
Watch
Understanding Agent Loop
Claude's Internal Architecture Revealed | How AI Agents Actually Work
ByteMonk
AI Agents Explained - How They Actually Work
LearnThatStack
§8 sources
Sources
Show all 8 sourcesHide sources
Anthropic (Dec 19, 2024). Building effective agents.
Yao, S. et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models. arXiv:2210.03629.
Shinn, N. et al. (2023). Reflexion: Language Agents with Verbal Reinforcement Learning. arXiv:2303.11366.
Yang, J. et al. (2024). SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering. arXiv:2405.15793.
Hou, X., Wang, S., Zhao, Y., Wang, H. (2026). When Agents Do Not Stop: Uncovering Infinite Agentic Loops in LLM Agents. arXiv:2607.01641.
Liu, N. F. et al. (2023). Lost in the Middle: How Language Models Use Long Contexts. arXiv:2307.03172.
Anthropic. How the agent loop works, Claude Agent SDK documentation (a vendor page, used only for the Claude Agent SDK).
Vercel. Loop Control, AI SDK documentation (a vendor page, used only for the AI SDK).





