How the agent loop works

​

The loop at a glance

1. Receive prompt. Claude receives your prompt, along with the system prompt, tool definitions, and conversation history. The SDK yields a SystemMessage with subtype "init" containing session metadata.
2. 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 objects, one for each content block, such as a text block or a tool call request.
3. 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 to intercept, modify, or block tool calls before they run.
4. 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.
5. Return result. The SDK yields a final AssistantMessage with the text response (no tool calls), followed by a ResultMessage with the final text, token usage, cost, and session ID.

​

Turns and messages

1. Turn 1: Claude calls Bash to run npm test. The SDK yields an AssistantMessage with the tool call, executes the command, then yields a UserMessage with the output (three failures).
2. Turn 2: Claude calls Read on auth.ts and auth.test.ts. The SDK yields an AssistantMessage for each call and returns the file contents.
3. Turn 3: Claude calls Edit to fix auth.ts, then calls Bash to re-run npm test. All three tests pass. The SDK yields an AssistantMessage for each call.
4. Final turn: Claude produces a text-only response with no tool calls: “Fixed the auth bug, all three tests pass now.” The SDK yields a final AssistantMessage with this text, then a ResultMessage with the same text plus cost and usage.

​

Message types

• SystemMessage: session lifecycle events. The subtype field distinguishes them:
  • "init": session metadata for the run. When a SessionStart or Setup hook runs during session startup, its hook lifecycle messages arrive before the init message
  • "compact_boundary": fires after compaction
  • "informational": plain-text status banners from the loop
  • "worker_shutting_down": the host is exiting or Remote Control disconnected
  In TypeScript, each subtype other than "init" is its own type in the SDKMessage union rather than a subtype of SDKSystemMessage.
• AssistantMessage: emitted for each content block in Claude’s responses, including the final text-only one. Each carries a single content block, such as text or a tool call, and the messages from one response share a message ID.
• UserMessage: emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop.
• StreamEvent: only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See Stream responses.
• ResultMessage: marks the end of the agent loop. Contains the final text result, token usage, cost, and session ID. Check the subtype field to determine whether the task succeeded or hit a limit. A small number of trailing system events, such as prompt_suggestion, can arrive after it, so iterate the stream to completion rather than breaking on the result. See Handle the result.

​

Handle messages

• Final results only: handle ResultMessage to get the output, cost, and whether the task succeeded or hit a limit.
• Progress updates: handle AssistantMessage to see what Claude is doing each turn, including which tools it called.
• Live streaming: enable partial messages (include_partial_messages in Python, includePartialMessages in TypeScript) to get StreamEvent messages in real time. See Stream responses in real-time.

• Python: check message types with isinstance() against classes imported from claude_agent_sdk (for example, isinstance(message, ResultMessage)).
• TypeScript: check the type string field (for example, message.type === "result"). AssistantMessage and UserMessage wrap the raw API message in a .message field, so content blocks are at message.message.content, not message.content.

import asyncio
from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock


async def main():
    try:
        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}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant") {
      // Each assistant message carries one content block
      for (const block of message.message.content) {
        if (block.type === "text") {
          console.log(`Claude: ${block.text}`);
        } else if (block.type === "tool_use") {
          console.log(`Tool call: ${block.name}`);
        }
      }
    }
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(message.result);
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

Tool execution

​

Built-in tools

• Connect external services with MCP servers (databases, browsers, APIs)
• Define custom tools with custom tool handlers
• Load project skills via setting sources for reusable workflows

​

Tool permissions

• allowed_tools / allowedTools auto-approves listed tools. A read-only agent with ["Read", "Glob", "Grep"] in its allowed tools list runs those tools without prompting. Tools not listed are still available, and calls to them that need approval fall through to the permission mode and canUseTool.
• disallowed_tools / disallowedTools blocks listed tools, regardless of other settings. See Permissions for the order that rules are checked before a tool runs.
• permission_mode / permissionMode controls how much human oversight you want. The SDK evaluates the active mode together with your allow and deny rules in a fixed order, described in How permissions are evaluated. See Permission mode for available modes.

​

Parallel tool execution

​

Control how the loop runs

​

Turns and budget

​

Effort level