Claude Agent SDK: Agent Loops, Tool Calls, and Multi-Step Workflows

The Claude Agent SDK is a programmatic wrapper for Claude Code's agentic capabilities, providing access to features such as tool use, multi-turn interactions, and session management without requiring developers to build all that orchestration themselves.

Why the Claude Agent SDK Changes Agentic Workflow Engineering

Engineers building agentic workflows with the Anthropic Messages API repeatedly write the same boilerplate: call messages.create(), check stop_reason == "tool_use", execute tools locally, loop. The Claude Agent SDK eliminates that loop by making Claude the autonomous executor. The agent can reason across multiple turns and use configured tools to complete tasks autonomously.

The SDK ships as two packages: claude-agent-sdk for Python and @anthropic-ai/claude-agent-sdk for TypeScript. Backend configuration is supported via environment variables.

The practical question for production engineering teams is where the SDK delivers value and where it requires external infrastructure. Teams managing complex multi-service codebases with hundreds of thousands of files need answers to both questions before committing to an architecture.

What the Claude Agent SDK Ships (and What It Doesn't)

The Claude Agent SDK provides autonomous tool execution, a configurable permission system, structured outputs, streaming, cost tracking, and session resumption. The tool inventory includes over 20 built-in tools spanning file operations (Read, Write, Edit), search (Glob, Grep), shell execution (Bash), web access (WebFetch, WebSearch), and agent spawning (Agent).

The SDK does not provide built-in retry logic, default turn or budget limits, durable execution, multi-tenant deployment, or centralized observability. max_turns defaults to unlimited, and max_budget_usd is an optional budget cap rather than an enforced default limit, so a production agent without explicit limits may run for many turns and accumulate cost without a circuit breaker.

Setup and Authentication: What the Docs Cover and What They Miss

Installation follows standard package management. The SDK quickstart covers the basics:

# Python via uv (recommended)
uv init && uv add claude-agent-sdk

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

Authentication uses ANTHROPIC_API_KEY by default. For CI/CD environments, claude setup-token generates a long-lived OAuth token.

The documentation has gaps that matter in production. Minimum versions are specified: Python 3.10+ and Node.js 18+. The Python SDK automatically bundles the Claude Code CLI. Enterprise engineers working behind proxies must locate the network config page for HTTPS_PROXY and the certificate store settings independently; this configuration is not surfaced in the quickstart.

Agent Loops: How the Core Execution Cycle Works

The agent loop follows a defined lifecycle documented in the agent loop reference. A SystemMessage with subtype "init" emits at loop start. Claude evaluates the prompt, then either calls tools to produce an AssistantMessage with tool-use blocks or produces a final answer. Tool results feed back into the loop. This repeats until termination.

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Refactor auth middleware per spec.md",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash"],
        setting_sources=["project"],
        max_turns=20,
        effort="high"
    )
):
    if hasattr(message, 'subtype') and message.subtype == "success":
        print(message.result)

Several conditions can terminate the loop, reflected in ResultMessage.subtype:

• "success": Claude produces a final answer with no further tool calls
• "error_max_turns": the max_turns limit is reached
• "error_max_budget_usd": the max_budget_usd limit is reached

Read-only tools like Read, Glob, and Grep can execute in parallel within a single turn; the SDK merges their results before the next reasoning step. Stateful tools such as Edit, Write, and Bash execute sequentially. The readOnlyHint property also controls this classification for custom tools.

Hooks intercept the loop at defined points. PreToolUse hooks fire before tool execution and can block or modify tool calls. PostToolUse hooks fire after execution for audit logging, though they cannot undo completed actions. A PreToolUse hook can block a tool call entirely, which is how teams enforce guardrails like "no production writes." The hooks reference documents these interception points.

Tool Calls: Defining Tools, Handling Responses, and Error Recovery

The SDK supports built-in, custom, and MCP tools. Tool permission configuration has a critical distinction that the documentation buries:

Scoped Bash permissions provide granular control: configuring "allow": ["Bash(npm *)"] auto-approves only Bash commands starting with npm.

Custom Tool Definition with Error Recovery

Custom tools register via create_sdk_mcp_server and follow MCP naming conventions (mcp__<server-name>__<tool-name>):

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("get_temperature", "Get current temperature for a location",
      {"latitude": float, "longitude": float})
async def get_temperature(args: dict) -> dict:
    try:
        temp = await fetch_weather(args["latitude"], args["longitude"])
        return {"content": [{"type": "text", "text": f"Temperature: {temp}°C"}]}
    except Exception as e:
        return {
            "content": [{"type": "text", "text": f"Error: {str(e)}"}],
            "isError": True,
        }

The isError: True return is the single most important pattern in custom tool development. When a handler throws an uncaught exception, the agent loop stops. Claude never sees the error. The query() call fails. When a handler returns isError: True, the agent loop continues. Claude sees the error as data and can retry or adapt. Always catch exceptions and return isError: True for recoverable failures.

Tool Execution Patterns

• Sequential execution (default for stateful operations): Claude calls one tool per turn, such as Read followed by analysis, followed by Edit. Standard for git workflows where each step depends on the previous result.
• Parallel execution (read-only tools): Claude issues multiple Read, Glob, and Grep calls in a single turn. The SDK merges results before the next reasoning step.
• Dynamic tool discovery: With ENABLE_TOOL_SEARCH, tool definitions load on demand rather than dumping full schemas into context every turn.

Multi-Step Workflows: Chaining Agents and Managing State

Single-session tasks work well within the agent loop. Multi-step workflows that span multiple context windows require explicit patterns. Without a strategy, long-running tasks can fail in at least one documented way described by long-running agents: the agent runs out of context mid-implementation, leaving undocumented partial work.

Initializer + Coding Agent Split

Anthropic's recommended primary pattern for long-running tasks uses a three-agent architecture with planner, generator, and evaluator roles. A simpler alternative separates two distinct roles. The initializer agent, in the first context window, sets up the environment, writes a feature list, creates test scripts, and documents project state. The coding agent, in every subsequent session, runs the initializer's setup script first, verifies the app works, and then focuses on incremental progress.

Session Chaining via Shell Loop

For fully autonomous work, a continuous loop spawns fresh sessions:

#!/bin/bash

while true; do
  COMMIT=$(git rev-parse --short=6 HEAD)
  LOGFILE="agent_logs/agent_${COMMIT}.log"
  claude --dangerously-skip-permissions \
    -p "$(cat AGENT_PROMPT.md)" \
    --model claude-opus-X-Y &> "$LOGFILE"
done

State lives in the git repository, not the context window. The agent breaks work into small pieces, tracks progress via commit history and task lock files, and determines what to work on next based on the repository state.

Session Resumption via SDK

from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

session_id = None

async for message in query(
    prompt="Read the authentication module",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.data["session_id"]

async for message in query(
    prompt="Now find all callers of that module",
    options=ClaudeAgentOptions(resume=session_id),
):
    if isinstance(message, ResultMessage):
        print(message.result)

Field-Tested Gotchas: Undocumented Edge Cases and Configuration Defaults

Production engineers have reported several issues not covered in the official SDK documentation. Some items below are community-reported and may not reflect current SDK behavior; treat them as signals to verify against your own deployment rather than confirmed bugs.

Reasoning History Wipe Bug (Reported)

Engineers reported that a bug shipped on March 26, 2026, caused thinking history to be wiped on every subsequent turn for the rest of a session. Affected agents reportedly continued to execute but progressively lost the rationale for their earlier decisions, leading to drift in long-running sessions. This issue has not been documented in the available Claude Code release notes and should be treated as unconfirmed until independently reproduced.

max_turns Error Results Did Not Set is_error: true

A changelog entry notes that error result messages for error_during_execution, error_max_turns, and error_max_budget_usd were fixed to correctly set is_error: true. Automated pipelines checking is_error silently treated a max-turns termination as success. Always check message.subtype rather than is_error.

disallowedTools Case Mismatch (Reported)

Engineers have reported that AgentDefinition uses camelCase (disallowedTools), while ClaudeAgentOptions uses snake_case (disallowed_tools). Using the wrong casing on either interface reportedly results in a silent no-op: no error, no warning, no enforcement. Verify this against current SDK versions before treating it as a live issue.

CLAUDE.md Changes Ignored on Session Resume (Reported)

When using claude --resume <id>, instruction changes in CLAUDE.md are reportedly silently ignored until the session rotates. CLAUDE.md instructions are delivered as user context, not as a system prompt. Engineers who need fresh instructions should start a new Claude CLI session using the documented session management approaches.

Session Resumption Breaks Across Versions (Reported)

Engineers have reported that sessions created on Claude Code ≤2.1.97 cannot resume on version 2.1.120. Pin both the SDK package version and the CLI version for production deployments until this is confirmed resolved.

Where the SDK Stops and a Platform Layer Starts

The Claude Agent SDK uses a subprocess architecture, spawning the Claude Code CLI as a subprocess, and is also designed for service deployment. A Python application makes subprocess calls to a Node.js runtime where agent logic executes. This architecture creates specific boundaries for production use:

• Observability: The SDK produces no structured telemetry by default. Tracing every tool call, retrieved data, and reasoning step requires external tooling.
• Durable execution: Agent sessions can be resumed and persisted, depending on configuration. Each claude -p session starts fresh unless the application builds persistence above it.
• Multi-agent coordination: The SDK supports subagents with isolated context; coordination is managed by the main agent, and the documentation does not describe shared context or built-in coordination primitives between agents.
• Team-scale permissions: No centralized policy enforcement, no RBAC, and no built-in audit trail.

When teams need coordinated multi-agent work, Intent adds living specs, isolated workspaces, and resumable state on top of the lower-level SDK behavior. Intent's Context Engine processes 400,000+ files to give every agent in the workflow precise architectural context before work begins. Teams already using Claude Code can run those agents within Intent's coordination layer through its BYOA (Bring Your Own Agent) model.

Choose a Coordination Layer Before Scaling Agent Work

The Claude Agent SDK handles autonomous tool execution and multi-turn reasoning well for single-agent, single-developer workflows. The boundary appears when teams need coordinated agents, persistent state, and shared architectural context across large codebases. Engineers who treat context management as a first-class engineering concern (budgeting it, monitoring it, and actively managing what enters and leaves the window) will see better outcomes than those who treat it as an implementation detail. Intent's living specs and coordinated agent model address the structural gaps where the SDK stops: parallel execution with shared context, persistent workspaces, and spec-driven alignment across every agent in the workflow.

Frequently Asked Questions About the Claude Agent SDK

Related Guides

• 5 Autonomous Agents for End-to-End Feature Automation
• AI Coding Agents vs Autocomplete: 6 Key Architecture Gaps
• AI Agent Quality: 7 Frameworks to Go Beyond Vibe Coding
• 12 Ways Computer-Using Agents Transform IT Workflows
• Top CLI AI Agents for Enterprise Developers