Claude Agent SDK
also known as Claude Code SDK
Type: full-code · Vendor: Anthropic · Language: Python, TypeScript · License: MIT (Python), proprietary (TypeScript — Anthropic Commercial Terms) · Status: active · Status in practice: emerging · First released: 2025-06-11
Embed Claude Code's autonomous agent loop — same tools, same context management — as a programmable library in Python or TypeScript so production agents can read files, run commands, edit code, and execute multi-step workflows.
Description. The Claude Agent SDK is Anthropic's Python and TypeScript library for building agents that run Claude Code's loop inside your own process. It gives you the same tools, agent loop, and context management that power Claude Code, programmable in either language. The SDK exposes built-in tools (Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch/Agent/Skill), MCP servers (in-process and external), filesystem-defined Agents, Skills and Slash Commands under .claude/, hooks, and a canUseTool approval callback. It is the renamed successor of the Claude Code SDK; distinct from the lower-level Anthropic Client SDK (where you implement the tool loop) and from Managed Agents (Anthropic-hosted sandbox).
Agent loop shape. Imperative query() / ClaudeSDKClient loop that wraps the Claude Code harness. Receive prompt → evaluate and respond → execute tools → repeat → return result. Turns continue until Claude produces output with no tool calls. Caller caps the loop with max_turns / maxTurns, max_budget_usd / maxBudgetUsd, effort, and permission_mode. Subagents spawn via the Agent tool, run with their own fresh context, and return a single final message. Sessions persist as JSONL under ~/.claude/projects/ and can be resumed, continued, or forked.
Primary use cases
- production coding agents that mirror the Claude Code shape
- agents that need filesystem + bash + browser tools out of the box
- agents with mid-run approval gates via canUseTool
- agents using Anthropic skills and MCP servers
Key concepts
- Agent loop (docs) — Same execution loop that powers Claude Code; Receive → Evaluate → Execute tools → Repeat → Return result.
- Subagents → subagent-isolation (docs) — Separate agent instances the main agent can spawn for focused subtasks; their context starts fresh and intermediate tool calls stay inside the subagent.
- Agent Skills → agent-skills (docs) — Specialized capabilities packaged as SKILL.md files that Claude autonomously invokes when relevant; descriptions load at session start, full content only when used.
- MCP servers → mcp (docs) — Three transports — stdio, http/sse, and in-process SDK MCP servers; mcp_servers / mcpServers is a top-level option.
- Permission modes + canUseTool → approval-queue (docs) — Permission modes (default / dontAsk / acceptEdits / bypassPermissions / plan / auto-TS-only) layered with canUseTool callback that pauses execution until the host returns a decision.
- Hooks (docs) — Callback functions that run host code in response to agent events (PreToolUse, PostToolUse, PermissionRequest, Stop).
Patterns this full-code implements —
- ★★Augmented LLM
Anthropic defines the foundational agentic building block as an LLM enhanced with retrieval, tools, and memory that the model itself drives.
- ★MCP-as-Code-API
Anthropic presents MCP servers as a filesystem of typed code modules the model imports on demand, so intermediate tool data stays in the execution environment instead of the context window.
- ★★Lead Researcher
A LeadResearcher analyzes the query, develops a strategy, and spawns subagents in parallel to explore different aspects simultaneously, then synthesizes their returned findings.
- ★Reasoning Trace Carry-Forward
Claude requires thinking/reasoning blocks to be passed back unmodified across tool-use turns to preserve reasoning continuity, while a non-tool-result user block ends the episode and strips prior thi…
- ·Planner-Generator-Evaluator Harness
A planner expands a short prompt into a full spec, a generator works one feature per sprint against that spec, and a separate evaluator grades each sprint against criteria the generator never sees —…
- ★★Agent Resumption
Sessions persist as JSONL on disk; resume by sessionId restores full context. continue (TS) / continue_conversation (Py) and fork_session also supported. Subagents themselves are resumable.
- ★Agent Skills
Skills are markdown procedures loaded on demand from .claude/skills/ and ~/.claude/skills/; descriptions surface at session start, full content only when invoked.
- ★★Approval Queue
canUseTool callback pauses the loop on tool requests; permission evaluation order is hooks → deny rules → permission mode → allow rules → canUseTool. Callbacks can stay pending indefinitely.
- ★★Model Context Protocol
Three transports — stdio, HTTP, and in-process SDK MCP servers; mcp_servers / mcpServers top-level option.
- ★Skill Library
Skill selection at session start via Pass-a-list or 'all'; description-first loading lets a large skill catalogue stay cheap.
- ★★Step Budget
Caller caps the loop with max_turns / maxTurns (counts tool-use turns only) and max_budget_usd / maxBudgetUsd; exceeding emits a ResultMessage with error_max_turns or error_max_budget_usd.
- ★★Structured Output
outputFormat / output_format option accepts a JSON Schema (or Zod / Pydantic via .toJSONSchema / .model_json_schema); SDK validates output, re-prompts on mismatch, surfaces error_max_structured_outpu…
- ★Subagent Isolation
Each subagent runs in its own fresh conversation; intermediate tool calls/results stay inside and only the final message returns to the parent. Subagents cannot spawn subagents.
- ★★Tool Use
Built-in tools (Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch/Agent/Skill/AskUserQuestion/Monitor) + custom tools via @tool / create_sdk_mcp_server + external MCP servers.
- ★Tool-Result Eviction
The clear_tool_uses strategy clears the oldest tool results once context grows past a threshold and replaces each with placeholder text so the model still knows the call happened.
- ★Context Compaction
Claude's compaction feature automatically summarizes older context when nearing the context-window limit and replaces that stale span with a concise model-written summary so long-running tasks contin…
- ★★Extended Thinking
ThinkingConfig and effort parameter expose Claude's reasoning behaviour. On Opus 4.7 manual extended thinking is no longer supported; adaptive thinking with effort replaces it. Downgraded from first-…
- ★★Tool Result Caching
Prompt caching of the running context (system prompt, tool definitions, CLAUDE.md, accumulated history) is automatic; this is not deduplicated caching keyed on individual tool calls.
Neighbourhood
Click any neighbour to follow the lineage. Scroll to zoom, drag to pan.
Instantiates
Anti-patterns avoided
- ★Tool Output Poisoning Defense
Hooks + deny rules + canUseTool allow explicit interception of every tool invocation before execution; the SDK warns that allowed_tools does not constrain bypassPermissions and that an allow-list pai…
- ✕Agent Privilege Escalation
Least-privilege tool allowlists: anything not explicitly approved is denied outright rather than prompted, blocking capability escalation.
- ✕Context Anxiety
Context-awareness gives the model its real remaining token budget so it persists to the end instead of guessing how many tokens remain and wrapping up early.
- ✕Tool Over-Broad Scope
Scoped deny rules (e.g. Bash(rm *)) enforce fine-grained least-privilege limits inside an otherwise-available tool, in every permission mode.
Alternatives & relatives
- full-code · framework
Claude Code
Same capabilities, different interface — Claude Code is the CLI/IDE product; Claude Agent SDK is the library that exposes the same loop.
- full-code · framework
OpenAI Agents SDK
Cross-vendor SDK in the same agent-SDK category.
- full-code · framework
Agent Development Kit (ADK)
Same category, Google equivalent.
- full-code · framework
Vercel AI SDK
TypeScript-first competitor in the same category.
- full-code · framework
OpenAI Swarm
Same category, different vendor.
- full-code · framework
TaskWeaver
Listed as alternative by (10)
- full-code · framework
- full-code · framework
Anthropic Citations API
- full-code · framework
- full-code · framework
Cloudflare Code Mode
- full-code · framework
- full-code · framework
- full-code · framework
Stainless (API MCP server architecture)
- full-code · framework
- full-code · framework
- full-code · framework
x402
References
Provenance
- Last analyzed:
- Last updated:
- Verification status: needs-verification