How the agent loop works changedagent-sdk/agent-loop
Nearest release: v2.1.312, published 23 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 28 Oct 2026 18:03 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 28 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+3added
Lines−3removed
From line
17
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits27to this page, all time
The whole hunk
from line 17, old and new numbered
/
from line 17
17171. **Receive prompt.** Claude receives your prompt, along with the system prompt, tool definitions, and conversation history. The SDK yields a [`SystemMessage`](#message-types) with subtype `"init"` containing session metadata.
18182. **Evaluate and respond.** Claude evaluates the current state and determines how to proceed. It may respond with text, request one or more tool calls, or both. The SDK yields one or more [`AssistantMessage`](#message-types) objects, one for each content block, such as a text block or a tool call request.
19193. **Execute tools.** The SDK runs each requested tool and collects the results. Each set of tool results feeds back to Claude for the next decision. You can use [hooks](https://code.claude.com/docs/en/agent-sdk/hooks.md) to intercept, modify, or block tool calls before they run.
204. **Repeat.** Steps 2 and 3 repeat as a cycle. Each full cycle is one turn. Claude continues calling tools and processing results until it produces a response with no tool calls.
204. **Repeat.** Steps 2 and 3 repeat as a cycle. Claude continues calling tools and processing results until it produces a response with no tool calls.
21215. **Return result.** The SDK yields a final [`AssistantMessage`](#message-types) with the text response (no tool calls), followed by a [`ResultMessage`](#message-types) with the final text, token usage, cost, and session ID.
2222
23A quick question ("what files are here?") might take one or two turns of calling `Glob` and responding with the results. A complex task ("refactor the auth module and update the tests") can chain dozens of tool calls across many turns, reading files, editing code, and running tests, with Claude adjusting its approach based on each result.
23A quick question such as "what files are here?" might take two or three [turns](#turns-and-messages): one or two calling `Glob`, then one responding with the results. A complex task such as "refactor the auth module and update the tests" can chain dozens of tool calls across many turns as Claude adjusts after each result.
2424
2525## Turns and messages
2626
27A turn is one round trip inside the loop: Claude produces output that includes tool calls, the SDK executes those tools, and the results feed back to Claude automatically. This happens without yielding control back to your code. Turns continue until Claude produces output with no tool calls, at which point the loop ends and the final result is delivered.
27A turn is one pass through the loop: Claude produces output, and if it includes tool calls, the SDK executes them and the results feed back to Claude automatically. This happens without yielding control back to your code. Turns continue until Claude produces output with no tool calls, at which point the loop ends and the final result is delivered.
2828
2929Consider what a full session might look like for the prompt "Fix the failing tests in auth.ts".
3030
No line in this hunk matches that.