Claude Agent SDK: The Agent Loop, Messages and Hooks

1.Three ways to build a Claude agent

Before you write any agent code, decide who runs the loop. Anthropic offers three routes, and they differ on exactly that point. The Agent SDK is a library you embed in your own Python or TypeScript application. It runs the Claude Code binary for you, so your process gets the same loop, built-in tools, permissions, sessions and hooks that Claude Code uses. The Client SDK is one level lower. It calls the Claude API directly, and you write the tool loop yourself (or hand it to the Client SDK's beta tool runner). This is the custom-loop route: you own every step of the harness. Managed Agents moves the loop to Anthropic. It is a hosted harness, configured through the Claude API.

The Agent SDK is more than a loop runner. It ships the capabilities you would otherwise have to build: built-in tools for files, commands and web search; hooks; subagents that spawn specialised agents for focused subtasks; MCP connections to external tools and data; permissions that decide which tools run automatically; and sessions you can resume or fork. It also loads skills, commands and memory from .claude/ and ~/.claude/, the same way Claude Code does. The Managed Agents docs describe the trade-off from the other side: the Messages API is best when you need custom agent loops and fine-grained control.

Sources12

2.One run of the loop, message by message

Calling query() starts the loop. First, Claude receives your prompt together with the system prompt, the tool definitions and the conversation history. This is where your agent's system prompt and registered tools take effect. The SDK announces the start with a SystemMessage of subtype "init", which carries session metadata. Claude then evaluates the state and returns text, one or more tool calls, or both. The SDK runs each requested tool and feeds the results back for Claude's next decision. Each full cycle of evaluate-then-execute counts as one turn. In the docs' bug-fix example, Claude runs npm test, reads auth.ts and its test file, edits the fix and runs the tests again. It then ends with a text-only reply, and that reply closes the loop.

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}")

Two details trip up real code. First, a ResultMessage does not guarantee success: its subtype tells you whether the task succeeded or hit a limit. Second, a few trailing system events, such as prompt_suggestion, can arrive after the result, so iterate the stream to the end instead of breaking out at the result. The languages also differ in how you read messages. Python checks types with isinstance(). TypeScript checks the type string and wraps the raw API message, so content blocks live at message.message.content. A single-shot query() also raises after yielding an error result, so wrap the loop in a try block.

Sources3

3.Hooks: deterministic code at fixed points in the loop

The model decides which tool to call next. Some rules should never be left to that decision: never write .env, log every tool call, get a human's approval before a database write. Hooks cover these cases. A hook is your own code, and the SDK runs it at a fixed point in the agent lifecycle, whatever the model intended. The loop has a clear place for them: between Claude's request and the tool's execution, a hook can intercept, modify or block the call. The flow is always the same. An event fires, the SDK collects the hooks registered for it, matchers filter which ones run, the callbacks execute, and each callback returns a decision.

options = ClaudeAgentOptions(
        hooks={
            # Register the hook for PreToolUse events
            # The matcher filters to only Write and Edit tool calls
            "PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]
        }
    )

# Block the operation if targeting a .env file
    if file_name == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }

    # Return empty object to allow the operation
    return {}

Blocking is only one use. The docs also list auditing every tool call, changing inputs and outputs (sanitising data, injecting credentials, redirecting file paths), requiring human approval, and tracking the session lifecycle. Which events you can hook depends on the language. The TypeScript SDK exposes far more events than the Python SDK.

Sources341

Exam traps

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

1. 1.As soon as the ResultMessage arrives, it is safe to break out of the message loop.Why is that wrong?

   A small number of trailing system events, such as prompt_suggestion, can arrive after the result. The docs say to iterate the stream to completion.

   Covered in One run of the loop, message by message

2. 2.In TypeScript, an assistant message's content blocks are at message.content, just as in Python.Why is that wrong?

   The TypeScript SDK wraps the raw API message in a .message field, so the blocks are one level deeper.

   Covered in One run of the loop, message by message

3. 3.Every hook event is available in both the Python and TypeScript Agent SDKs.Why is that wrong?

   Many events are TypeScript-only. SessionStart, SessionEnd, PostToolBatch and PostCompact, for example, are not available in the Python SDK.

   Covered in Hooks: deterministic code at fixed points in the loop