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 —
- ★★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.
- ★★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
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.
Listed as alternative by (6)
References
Provenance
- Last analyzed:
- Last updated:
- Verification status: verified