Tool-Use Loops and the Claude Agent SDK Agent Loop

1.The contract underneath every agent

Every agent pattern in this subdomain rests on one mechanism, tool use. Your application declares which operations exist and what their inputs and outputs look like. Claude decides when to call them and with what arguments. Claude never runs anything itself. It emits a structured request, something else executes it, and the result flows back into the conversation.

What changes from tool to tool is where the code runs, and that decides what your application has to do. There are three cases:

- User-defined tools. You write the schema, run the code and return the result in a tool_result block. Claude sees only your schema and your result, never your implementation. - Anthropic-schema tools (memory, bash, text_editor, computer, browser). Anthropic publishes the schema and your application runs the operation. Claude has been trained on these exact signatures, so it calls them more reliably than a custom tool that does the same job. - Server tools (web_search, web_fetch, code_execution, tool_search). Anthropic runs the code, and you never build a tool_result for them.

Sources1

2.The client-side loop, keyed on stop_reason

Claude can't run your code, so every client-executed tool call is a round trip: the model asks, you execute, you report back, the model continues. This round trip is the tool-use loop, the most basic agent pattern:

1. Send a request with your tools array and the user message. 2. Claude responds with stop_reason: "tool_use" and one or more tool_use blocks. 3. Execute each tool and format the outputs as tool_result blocks. 4. Send a new request containing the original messages, Claude's response, and a user message holding the tool_result blocks. 5. Repeat from step 2 while stop_reason is "tool_use".

The loop exits on any other stop reason: "end_turn", "max_tokens", "stop_sequence" or "refusal". Claude has either produced a final answer or stopped for a reason your application has to handle.

Server tools run their own loop inside Anthropic's infrastructure, so a single request can trigger several searches before any response reaches you. That internal loop has an iteration limit. If Claude is still working when it hits the cap, the response comes back with pause_turn instead of end_turn. The work is not done: send the conversation again, including the paused response, and Claude continues where it left off. Control also comes back to you early when Claude calls a server tool and a client tool in the same group of parallel tool calls. In that case the server tool runs only after you return the client tool's results.

Sources1

3.The same loop, run for you: the Agent SDK's query()

Writing that while loop yourself is one option. The Claude Agent SDK is the other: it runs the same cycle for you. Claude receives your prompt along with the system prompt, tool definitions and conversation history. It evaluates the state and replies with text, tool calls or both. The SDK runs each requested tool and feeds the results back. That repeats until Claude produces a response with no tool calls.

The SDK documentation walks through a failing-test example. In turn 1 Claude runs npm test with Bash and sees three failures. In turn 2 it reads auth.ts and auth.test.ts. In turn 3 it edits auth.ts and runs the tests again, and all three pass. The final turn is text only, with no tool calls. Nobody scripted that sequence in advance: each tool result shaped the next decision.

The SDK hands the loop's progress to you as a stream of typed messages:

- SystemMessage. Session lifecycle events: init at the start, and compact_boundary after compaction. - AssistantMessage. One per content block, such as a text block or a tool call. - UserMessage. Tool results being sent back to Claude. - ResultMessage. Marks the end of the loop and carries the final text, token usage, cost and session ID.

You can also use hooks to intercept, modify or block tool calls before they run.

async for message in query(prompt="Summarize this project"):
            if isinstance(message, AssistantMessage):
                # Each AssistantMessage carries one content block
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")
                    elif isinstance(block, ToolUseBlock):
                        print(f"Tool call: {block.name}")
            if isinstance(message, ResultMessage):
                if message.subtype == "success":
                    print(message.result)
                else:
                    print(f"Stopped: {message.subtype}")

Sources2

4.When a tool loop is the right shape

A loop adds cost, so use one only when the task needs something the model can't do from text alone:

- actions with side effects, such as sending an email or writing a file - fresh or external data - output with a guaranteed structure - calls into existing systems such as databases and internal APIs

A practical test from the documentation: if you are writing a regex to pull a decision out of model output, that decision should have been a tool call.

The opposite also holds. Summarization, translation and general-knowledge questions can be answered from training alone. One-shot Q&A with no side effects gives a tool nothing to do. For a trivial response, the extra round trip can cost more than the work itself.

Sources1

5.Sub-agents and context-window management

A long-running agent has two linked problems: the loop keeps adding to the context window, and one agent may have to do several kinds of work. Sub-agents and context management address both.

Sub-agents. A subagent is a separate agent that the main agent delegates a task to. In the Agent SDK you define one programmatically with the agents parameter in your query() options, as a markdown file in .claude/agents/, or you rely on the built-in general-purpose subagent, which Claude can invoke through the Agent tool. A programmatic definition needs a description, which tells Claude when to use the subagent, and a prompt, which is its system prompt. It can also set tools to restrict what the subagent can do and model to override the model. The Agent tool must be available to the parent, which is why the SDK example lists it in allowedTools. Sub-agents give you four things:

- Context isolation. Each subagent runs in its own conversation. Its intermediate tool calls and results stay inside it, and only its final message returns to the parent, so a research subagent can read dozens of files without filling the main conversation. - Parallelization. Independent subagents, such as a style checker, a security scanner and a test-coverage checker, can run concurrently. - Specialized instructions. Each subagent can have a tailored system prompt. - Tool restrictions. A doc-reviewer subagent limited to Read and Grep can analyze files but never modify them.

Context-window management. Everything in the request counts toward the window: the system prompt, every message including tool results, and your tool definitions, plus the output Claude generates. More context is not automatically better, because accuracy and recall degrade as the token count grows (context rot), so curating what is in context matters as much as how much space is left. The main tools are:

- Server-side compaction. The primary strategy for long-running conversations and agentic workflows. It summarizes earlier parts of the conversation on the server so the conversation can continue past the window limit. In the Agent SDK, a compact_boundary SystemMessage fires after compaction. - Context editing. Tool result clearing removes old tool results in agentic workflows, and thinking block clearing manages thinking blocks. - Context awareness. Some models track their remaining token budget during a conversation, so they can pace long-running tasks against the space that remains. - The memory tool. Claude stores what it learns in files and reads them back on demand instead of loading everything up front. This keeps the active context focused on the current task and lets work carry across sessions. It is client-side, so your application executes each memory operation.

Sources345

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.When Claude calls a tool, Claude runs that tool.Why is that wrong?

   Claude only emits a structured tool_use request. Your application runs client tools, and Anthropic's servers run server tools. The result then goes back into the conversation.

   Covered in The contract underneath every agent

2. 2.Any stop_reason other than tool_use means Claude has finished the task.Why is that wrong?

   With server tools, pause_turn means the internal loop hit its iteration limit and the work is unfinished. Send the conversation again so Claude can continue.

   Covered in The client-side loop, keyed on stop_reason

3. 3.The ResultMessage is the last item the SDK stream yields, so you can break as soon as it arrives.Why is that wrong?

   A few trailing system events can arrive after the ResultMessage, so read the stream to the end.

   Covered in The same loop, run for you: the Agent SDK's query()

4. 4.Every tool call and file a subagent reads is added to the parent agent's context window.Why is that wrong?

   A subagent runs in its own conversation. Its intermediate tool calls and results stay inside it, and only its final message returns to the parent.

   Covered in Sub-agents and context-window management