Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

What is an agent loop?

An agent loop is the cycle that turns a language model into an agent. The model reads the task and asks for a tool call. The harness runs the tool and sends the result back. It reads that and decides again. The loop ends when the model answers without asking for a tool, or when a limit stops it.

Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.

How it works

The model asks for a tool, the harness runs it and returns the output, and the cycle repeats until the model answers with no tool call.your promptthe modeldecides the next stepthe harnessruns tools, checks limitsfiles, shell, webthe answer1. task2. asks for a tool3. runs itoutput4. result, go again5. done, no tool call
  1. The model receives the prompt, the system prompt and the list of tools it may call, each with a schema.

  2. It replies with text, or with a request to call a tool and the arguments. In the Claude API the response's stop reason is then tool_use.

  3. The harness, the code around the model, runs the tool: reads a file, runs a command, calls an API. The model never runs anything itself.

  4. The output goes back as the next message. The model reads it and decides what to do next. One round trip is a turn.

  5. The loop ends when the model answers without a tool call, or when a cap such as a turn limit or a budget stops it.

    Anthropic's one-line version: agents are typically just LLMs using tools based on environmental feedback in a loop.

Source: Anthropic: Building effective agents

The agent loop versus a fixed workflow

Anthropic's guidance draws the line this way: a workflow is LLM calls and tools wired together along paths the developer fixed in code; an agent is a model that directs its own process and tool use. The agent loop is what makes the second one possible. There is no script saying "search, then read, then write". There is a model, a set of tools, and a while loop that keeps going as long as the model keeps asking for tools.

That is the whole mechanism, and it is worth seeing how small it is. The model cannot execute anything. It emits a structured request naming a tool and its arguments. Your code runs the operation and appends the result to the conversation. The model reads the result and emits the next request. Everything an agent does, from fixing a bug to booking a flight, is this cycle repeated.

Example: fixing a failing test

Give a coding agent "fix the failing tests in auth.ts". Turn one: it calls the shell to run the tests and gets three failures back. Turn two: it reads the two files the failures name. Turn three: it edits the source and runs the tests again, and they pass. Turn four: it writes "fixed, all three pass" with no tool call, and the loop exits. Four turns, three with tools. The same prompt against a different codebase might take forty, because the model decides the path as it learns what is there.

A collaborative example: an agent pulls a shared board, edits a file and publishes. If a teammate's agent published first, the publish comes back refused with the file and author named, so the agent pulls again, redoes its edit and publishes. The refusal is just another observation, and the loop handles it.

Why it matters

The loop is where ground truth enters. A model answering from memory can be confidently wrong; a model that just ran the tests knows whether they passed. Each turn feeds real feedback from the environment back in, which is why agents can recover from their own mistakes in a way a single answer cannot. It is also where the cost and the risk live: every turn is another model call carrying the whole history, and every tool call is an action in the world. The controls you have, a turn cap, a budget, permission prompts, hooks that can block a tool before it runs, and checkpoints where a person is asked, all sit on the loop.

Common mistakes

  • No stopping condition. Open-ended prompts such as "improve this codebase" never produce a final answer on their own. Set a turn or spend limit and treat hitting it as information, not failure.
  • Ignoring context growth. A verbose command can add thousands of tokens in one turn. Trim tool output, prefer targeted reads, and move big subtasks into a subagent so only its result returns.
  • Treating the loop as the intelligence. The loop is plumbing. The quality comes from the tools' design, their descriptions, and the feedback they return. A tool that fails silently gives the model nothing to reason about.

FAQ

How does an agent loop know when to stop?
The normal exit is the model itself: it replies with text and no tool request, which the Claude API reports as stop reason end_turn instead of tool_use. The other exits are external: a maximum number of turns, a spend budget, a hook that blocks the next tool, or a person interrupting.
What counts as one turn in an agent loop?
One round trip: the model produces output with tool calls, the harness runs them, and the results go back. A quick question might take one or two turns. A refactor can take dozens. The Claude Agent SDK's maxTurns option counts these tool-use round trips.
Why does an agent loop get slower and pricier the longer it runs?
Nothing is forgotten between turns. Every tool result, file read and command output stays in the context window, so each new request carries all the earlier ones. Long sessions end up compacting older history into a summary, and good harnesses send big subtasks to subagents so only their final answer comes back.

Stop sending HTMLover Slack.

Create an account in a minute, connect your coding agent, and make your first board.