How the agent loop works
The agent loop is the cycle the SDK runs for every session: Claude is given the prompt and the tool list, it decides what to do, the SDK runs the tools it asked for, the results go back, and the cycle repeats until Claude answers with no tool calls left.
Last updated: 20 Oct, 2026 · Claude Agent SDK
The package is installed, so the next question is what it does once a prompt goes in. The agent loop page calls it the same execution loop that powers Claude Code, and it is the one idea the rest of this course hangs off: every tool, permission rule and hook is a decision taken somewhere inside it.
Walking the five steps of the loop
- Receive the prompt. Claude is given your prompt together with the system prompt, the tool definitions and the conversation history. The SDK opens the stream with a session-metadata message.
- Evaluate and respond. Claude reads the current state and decides how to carry on. It may answer with text, ask for one or more tool calls, or both. The SDK yields one message per content block, so text and a tool call arrive as two.
- Execute the tools. The SDK runs each requested tool and collects the results, and each set of results goes back to Claude for the next decision. This is where your hooks and permission rules get their say, before anything runs.
- Repeat. Steps two and three run as a cycle. One full cycle is one turn.
- Return the result. When Claude produces a response with no tool calls, the loop ends. The SDK yields that final text, then a closing message carrying the text again with the turn count, the token usage, the cost and the session id.
The documentation's own worked example is a prompt to fix failing tests. Claude runs the test command, reads two files, edits one and reruns the tests, then answers in words. That is four turns: three that called tools and one final text-only reply. A short question takes one or two; an open-ended one can chain dozens.
Nothing in steps two and three hands control back to your code on its own. Between your prompt and the final answer, the loop runs the tools and feeds the results back by itself. Your program sees each step as a message, and it influences the run through the options, the permission callback and the hooks it set up beforehand. The The messages you get back lesson names each of those messages.
Counting turns, and capping them
A turn is one round trip: Claude produces output that includes tool calls, the SDK runs them, the results feed back. The count that matters is tool-use turns only, so the final text-only reply is not one of them. Two options cap the loop, and the agent loop page states that both are off unless you set them:
- A turn cap stops the loop after a set number of tool-use round trips, and the run ends with a result whose subtype names the cap rather than a success.
- A spend cap stops it once the estimated cost of the session passes a threshold. The documentation warns that the cap is checked after each model response arrives, because the cost comes from the usage that response reports, so spend can pass the cap by the price of one response.
- With neither set the loop runs until Claude decides it is finished. That is reasonable for a well-scoped task and expensive on a prompt like improve this codebase.
Both options and the result subtypes they produce get a lesson of their own in Turn and budget limits.
What fills the context window
The context window is everything available to Claude during a session, and inside one session it does not reset between turns. It accumulates: the system prompt on every request, any project memory files, the tool definitions, and the whole conversation history including every tool input and every tool output. A command with verbose output can spend thousands of tokens in a single turn.
When the window approaches its limit the SDK compacts the conversation by itself: it summarises the older history to free space and keeps the recent exchanges. It announces that in the stream with a message whose subtype marks the boundary. The consequence is worth knowing early: a summary replaces the older messages, so an instruction given once at the start of a long session may not survive. Instructions that must hold belong in a project memory file, which is re-read on every request.
One turn against one session
| A turn | A session | |
|---|---|---|
| What it is | One round trip: Claude asks for tools, they run, results go back | One conversation, from the first prompt to the last |
| Who ends it | Claude, by producing output with no tool calls | Your code, or a cap, or the end of the input |
| What it is capped by | A turn cap, counting tool-use turns only | A spend cap, which accumulates across turns |
| What it leaves behind | Its messages in the context window | A session id you can resume or fork later |
| Context | Grows within the session | Compacted by the SDK when the window fills |
Where the loop's shape decides a design
- Choosing where a check belongs. A rule that must see every tool call has to sit inside the loop, as a hook, because the loop never pauses to ask your program otherwise.
- Budgeting a feature. Cost follows turns and tool output, not the length of your prompt, so an agent that reads twenty files costs more than one that answers from memory.
- Deciding what to put in the prompt. Anything that must hold for a long session belongs in a file the agent re-reads, because compaction can summarise an opening instruction away.
Related
- Previous: Installation and setup
- Next: SDK, CLI and Client SDK compared
- See also: Turn and budget limits
- Reference: How the agent loop works
- Take a task you would hand an agent and write down, turn by turn, which tools it would need and in what order.
- For that task, count how many turns you would allow before stopping it, and write the sentence you would show a user when the cap is hit.
- Name one instruction in that task that must survive a long session, and decide where it should live so compaction cannot summarise it away.
You understood something today that you didn't yesterday.