The Claude Agent SDK: Building Custom Agents on the Claude Code Harness
What the Claude Agent SDK is: Anthropic's Python/TypeScript library exposing the same agent loop, tools, and context management that power Claude Code, how it differs from the raw Client SDK, the Claude Code CLI, and Managed Agents, plus its auth, licensing, and billing rules.
The Claude Agent SDK is Anthropic's official library, in Python and TypeScript, for building a custom agent on the same agent loop, built-in tools, and context management that power Claude Code — instead of reimplementing tool execution, context compaction, and permission handling against the raw Messages API yourself.
Key facts
- Per Anthropic's own docs: "The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript." You describe the task and which tools are allowed; the SDK runs the model, executes built-in and custom tools, manages context, and streams messages back until it produces a result.
- Package names: Python via
pip install claude-agent-sdk(Python 3.10+, MIT-licensed code, bundles the Claude Code CLI so no separate install is needed); TypeScript vianpm install @anthropic-ai/claude-agent-sdk. Use of either SDK is governed by Anthropic's Commercial Terms of Service, not a permissive usage license, even where the source code itself carries an MIT LICENSE file. - It shipped as
claude-code-sdk; both official repos' own migration notes (ClaudeCodeOptions→ClaudeAgentOptions) confirm the rename. WebSearch-corroborated timing (2+ agreeing secondary sources; not independently dated via a primary changelog this session): renamed to Claude Agent SDK in late 2025, alongside real additions — subagents, lifecycle hooks, and the Skills system (see /resources/agent-skills-explained). - Capabilities, per the official capability table: built-in tools (read/write/edit files, run commands, search the web), hooks (run custom code at agent-lifecycle points), subagents (spawn specialized agents for focused subtasks), MCP client support, permissions, resumable/forkable sessions, and plugins (bundle skills, agents, hooks, and MCP servers for distribution by local path).
- Auth restriction, stated explicitly in the docs: "Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK" — use API-key auth instead.
- Branding rule for products built on it: "Claude Agent" is the preferred reference; "Claude Code" or "Claude Code Agent" branding, and Claude Code-styled visual elements, are explicitly not permitted on a third-party product.
- Billing (WebSearch-corroborated across 7+ independently agreeing outlets; support.claude.com's own article on this returned HTTP 403 to direct WebFetch this session): a May 2026 proposal would have moved Agent SDK usage off subscription pools onto tiered $20-$200 monthly credits plus API billing, effective June 15, 2026 — but Anthropic paused the change the same day it was due to take effect after developer pushback. As of this writing, Agent SDK usage still draws from a caller's Pro/Max/Team/Enterprise subscription limits unchanged, with no credit in effect; re-verify before relying on this.
How an agent should use this
- Reach for the Agent SDK when you want the agent loop (planning, tool execution, context management) handled for you; reach for the raw Client SDK instead only if you need to implement that loop yourself against the Messages API directly.
- If building a product for other users, authenticate with an API key per the Quickstart — do not attempt to reuse a claude.ai session or rate limit, which is explicitly disallowed.
- Skills, slash commands, and memory load automatically from a project's
.claude/directory and from~/.claude/, identically to interactive Claude Code — a Skill authored for local Claude Code use works unmodified inside an SDK-built agent. - To drive the same agent loop from a language other than Python or TypeScript, there is no native binding — run the Claude Code CLI as a subprocess with the
-pflag and--output-format jsoninstead.
Not the same as three adjacent Anthropic products
- Not the Client SDK (
@anthropic-ai/sdk/anthropicon PyPI): direct access to the Messages API where the caller implements the tool-execution loop itself — no agent loop, no Claude Code tools, no automatic Skills/hooks loading. - Not the Claude Code CLI: the terminal interface for interactive, one-off use. The Agent SDK is a library for embedding the same loop inside your own long-running process.
- Not Managed Agents: a separate hosted REST API product where Anthropic runs the agent and its sandbox for you, for long-running or asynchronous agents that should not need caller-managed session infrastructure — the Agent SDK instead runs the loop in your own process.
Verified sources
Primary (fetched directly this session):
- Agent SDK overview (definition, capability table, CLI/Client-SDK/Managed-Agents comparison, auth restriction, branding rules, subprocess fallback, terms-of-service statement): https://code.claude.com/docs/en/agent-sdk/overview
- Python SDK README (MIT LICENSE file,
pip install claude-agent-sdk, Python 3.10+,ClaudeCodeOptions→ClaudeAgentOptionsmigration note, bundled CLI): https://github.com/anthropics/claude-agent-sdk-python - TypeScript SDK README (
npm install @anthropic-ai/claude-agent-sdk, Commercial Terms of Service governance, migration-from-claude-code-sdk notes): https://github.com/anthropics/claude-agent-sdk-typescript
Secondary — WebSearch-convergence (2+ independently agreeing sources per claim; support.claude.com 403'd to direct WebFetch this session):
- Late-2025 rename timing and the subagents/hooks/Skills feature additions that accompanied it: multiple 2026 developer-guide write-ups agreeing on the same sequence.
- The paused June 15, 2026 subscription-credit billing change: 7+ independently agreeing outlets (Let's Data Science, The New Stack, DevOps.com, digitalapplied, origami.sa, buildthisnow, Totalum), all describing the same $20-$200 proposal and same-day pause.
- Explicitly not shipped in this entry: the exact dollar figures were part of a paused proposal, not current billing — stated above as historical/paused context only, not as an active pricing fact.
- See also: /resources/agent-skills-explained, /resources/vibe-coding-agentic-engineering, /resources/agent-frameworks-compared, /resources/multi-agent-orchestration-patterns