Claude Agent SDK: Claude Code's agent loop inside your own app

The Claude Agent SDK gives your application the same agent that runs in Claude Code: it plans, reads and edits files, runs shell commands, searches the web, calls MCP tools and delegates to subagents, with Claude Code's permission system, hooks and session history around it. You call query() with a prompt and options; the SDK drives the loop and streams messages back until the task is done or a limit stops it.

The SDK is a library in two languages: claude-agent-sdk for Python 3.10 or newer (0.2.165 on 8 October 2026) and @anthropic-ai/claude-agent-sdk for Node.js 18 or newer (0.3.296 on 9 October 2026). It was called the Claude Code SDK until Anthropic renamed it; old code imports claude_code_sdk and ClaudeCodeOptions. Use of the SDK is governed by Anthropic's Commercial Terms of Service, including when you build products for your own customers. The Python package's code carries an MIT licence file; the TypeScript package is proprietary.

Under the hood, query() spawns the claude CLI as a subprocess and talks to it over stdio. Both SDKs bundle a native Claude Code binary pinned to the SDK version, so updating the SDK updates the agent. The subprocess owns a shell, a working directory and session transcripts on local disk, which is why hosting it is closer to hosting a worker than a stateless API.

What comes built in:

• Tools. Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch, ToolSearch, and orchestration tools such as Agent (subagents), Skill, AskUserQuestion, TaskCreate and TaskUpdate.
• Custom tools and MCP. Your own functions become tools through an in-process MCP server; external MCP servers connect over stdio, HTTP or SSE.
• Permissions. Allow and deny rules, permission modes and an approval callback decide whether each tool call runs.
• Hooks. Callbacks at points such as PreToolUse, PostToolUse and SubagentStop can block, rewrite or log tool calls.
• Subagents, sessions, skills and plugins. Specialized agents with their own prompts and tools; resumable and forkable conversations; skills, commands and CLAUDE.md memory loaded from .claude/ directories.

In the stack, it is an agent harness you host yourself. Anthropic's own comparison puts it between the Client SDK (you write the tool loop, or use its tool runner, for tools you define) and Managed Agents (Anthropic hosts the loop and the sandbox). It works with Claude models through the Anthropic API, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Microsoft Foundry.

Pick the Agent SDK when:

• The agent works on files and commands. Code review, migrations, test fixing, report generation from a data directory, log triage: the built-in file and shell tools do most of the work.
• You want Claude Code's guardrails without rebuilding them. Permission modes, scoped rules like Bash(git log *), hooks and an approval callback are already there.
• Tasks are long and multi-step. The SDK handles context compaction, prompt caching, parallel tool calls and subagents.
• You already use Claude Code. Skills, subagent definitions, hooks and CLAUDE.md files your team wrote for Claude Code load into SDK agents.

Pick something else when:

• You need other model providers. The SDK runs Claude models only. LangGraph or a gateway-based loop keeps you portable.
• The job is one call or a short loop over your own tools. The Client SDK and its tool runner are less to host than a CLI subprocess per session.
• You do not want to run the infrastructure. Managed Agents hosts the loop and a per-session sandbox for you.
• You planned to let users sign in with their Claude subscription. Anthropic does not allow third-party products built on the SDK to offer claude.ai login or its rate limits unless previously approved. Use API keys or a cloud provider.

The loop. Claude receives your prompt with the system prompt, tool definitions and history; the SDK yields a SystemMessage with subtype init. Claude answers with text and tool calls; tools run (in parallel where possible); results go back; this repeats until Claude replies with no tool calls. The SDK then yields a final AssistantMessage and a ResultMessage holding the result text, token usage, an estimated total_cost_usd, num_turns, the session_id and a subtype that says whether it succeeded or hit a limit.

Limits. max_turns (maxTurns) counts tool-use round trips. max_budget_usd (maxBudgetUsd) stops the loop when estimated spend reaches the cap; the response that crosses it still completes, so spend can overshoot by one response plus whatever running subagents spend. Hitting either returns a ResultMessage with subtype error_max_turns or error_max_budget_usd. effort trades reasoning depth for tokens.

Context. Everything accumulates in one context window: system prompt, tool schemas, history and tool outputs. Stable parts are prompt-cached automatically. Near the limit, the SDK compacts older history into a summary and emits a compact_boundary system message; rules that must survive belong in CLAUDE.md, which is re-injected on every request.

Permissions, in order. For each tool call the SDK checks: hooks first (a hook can deny; a hook "allow" does not skip the next two steps), then deny rules (which win even in bypassPermissions mode), then ask rules, then the permission mode, then allow rules, then your can_use_tool callback. The modes:

Configuration loading. When you omit setting_sources (settingSources), the SDK reads the same files as the CLI: user, project and local settings, CLAUDE.md, and skills, agents, commands and hooks under .claude/. Pass an empty list to run only on what you configure in code.