Claude Agent SDK — Official Toolkit for Building Custom Agents

Source: wiki synthesis: anthropic-sdk-releases-may-2026, nate-herk-every-level-of-claude, certification-technical-reference, whats-new-2026-w21, raw/reddit-1u74va8.md

The Claude Agent SDK is Anthropic’s official toolkit for building custom agents that are not Claude Code itself. Claude Code is built on the same SDK, so the SDK exposes the agent loop, conversation management, and tool-handling primitives Anthropic’s own product uses ^[inferred]. It was originally shipped as the Claude SDK and renamed Agent SDK as the agent-construction story took center stage, distinguishing it from the lower-level Anthropic SDK (raw Messages API client).

Key Takeaways

• Two language bindings — Python and TypeScript — the SDK ships in both Python and TypeScript at version-locked parity ^[inferred from sibling Anthropic SDK release pattern in anthropic-sdk-releases-may-2026]. Nate Herk’s L5 framing names “Agent SDK (Python + TypeScript)” as the surface that lets developers “build products on top of Claude Code’s engine.”
• Tool-loop abstraction is the headline primitive. The SDK encodes the stop_reason → tool_use → execute → append-result → re-call loop documented in certification-technical-reference so callers don’t have to hand-roll it. Anti-patterns the loop avoids: parsing assistant text to detect completion, arbitrary iteration caps as the primary stop condition.
• Conversation context is managed for you. The raw Anthropic SDK is stateless — every request must include the full message history. The Agent SDK manages this state across multi-turn tool-calling sessions ^[inferred].
• AgentDefinition is the canonical configuration object (per certification-technical-reference): name, description, system_prompt, allowed_tools. Subagents are spawned via a Task tool that must be in the coordinator’s allowedTools — the hub-and-spoke multi-agent pattern is first-class.
• Hooks are deterministic guardrails — PreToolUse blocks policy-violating calls before execution; PostToolUse normalizes or trims tool results before the model sees them. Use hooks (not prompts) when failure has financial, legal, or safety consequences ^[exam-grade rule from certification-technical-reference].
• Post-Stainless release lockstep. All SDK releases through May 2026 were authored by stainless-app[bot]; Anthropic acquired Stainless on 2026-05-18 (anthropic-sdk-releases-may-2026), so the Agent SDK release pipeline is now owned outright. Expect Python and TS to keep shipping in version-locked pairs.
• Headless mode pairs with the SDK. claude -p runs Claude Code without a human session and pipes output anywhere — the natural composition surface for SDK-built agents that need to invoke Claude Code as a sub-process ^[inferred].

What the Agent SDK provides

• Tool loop — the canonical agentic loop (tool_use → execute → append-result → re-call until end_turn) implemented once, model-driven termination.
• Conversation history — automatic message-list construction and append across turns; callers configure rather than hand-assemble.
• MCP client integration — load MCP servers from .mcp.json and surface their tools, resources, and prompts to the agent ^[inferred from MCP being a first-class surface in certification-technical-reference].
• Structured streaming — incremental delivery of model output and tool-call events for UIs and pipelines ^[inferred].
• Retry logic — handling for transient errors (timeout, 503) versus validation/business/permission errors per the error-category taxonomy in certification-technical-reference ^[inferred].
• Prompt-caching helpers — May 2026’s cache-diagnostics beta (Python v0.102.0, TS sdk-v0.96.0) closes the “is my cache hitting?” measurement gap and lets SDK callers optimize the 60-90% long-session cost reduction Nate Herk’s L4 surfaces.

Agent SDK vs Anthropic SDK vs Claude Code

Surface	What it is	When to use
Anthropic SDK	Raw Messages API client (Python + TS). Stateless. You assemble the message list, send tool definitions, parse stop_reason, run your own loop.	Single-turn calls, custom transports, when you need maximum control over every request.
Claude Agent SDK	Higher-level layer over the Anthropic SDK. Tool loop, conversation management, subagents, hooks, MCP client all built in.	Building a custom agent — anything from a one-off automation to a productized agent surface — without re-implementing the loop.
Claude Code	The Anthropic-built agent product. Itself built on the Agent SDK ^[inferred]. Adds CLI, filesystem tools, plan mode, worktrees, routines, channels.	Coding tasks, terminal workflows, the L4-L5 stack from nate-herk-every-level-of-claude.

Billing: separate SDK credit pool (effective June 15, 2026)

Update 2026-06-16 — change deferred

Anthropic deferred this change. A first-party email (quoted verbatim in r/Anthropic, 2026-06-16) states the Agent SDK / claude -p / third-party-app billing move to a dedicated monthly credit is not taking effect — “we’re not making this change today… usage continues to work with your subscription exactly as it did before… subscription limits are unchanged” — pending a revised plan that Anthropic says it will announce with advance notice.

From June 15, 2026, programmatic usage — claude --print / -p jobs and Claude Agent SDK runs — bills against a separate monthly SDK credit bucket instead of the Pro/Max plan’s CLI tokens. Plans include an SDK credit allowance (community reports suggest ~$100/mo on Max), but heavy programmatic use will exceed it. Patterns the community flagged as newly uneconomical: long-running orchestrators, supervisor + worker fan-outs, always-on cron-driven agents. Audit orchestration code with grep -r 'claude --print\|claude -p' . before the cutover — each match is a workflow to migrate to native CLI surfaces (interactive mode, Routines, agent view) or to budget explicitly against the SDK bucket. Full coverage: W21 release digest (canonical Anthropic doc: support.claude.com article 15036540, “Use the Claude Agent SDK with your Claude plan”).

Related

• How the Agent Loop Works — primary-source mechanics of the SDK’s message lifecycle, turns, the five message types, permissions, budgets, compaction, and hooks (the first-party anchor for this article’s tool-loop claims).
• anthropic-sdk-releases-may-2026
• whats-new-2026-w21
• nate-herk-every-level-of-claude
• certification-technical-reference
• anthropic-cookbook-managed-agents-multiagent-outcomes
• mcp
• subagents
• hooks
• Kahn v. Anthropic (usage-limits class action) — the consumer-side dispute over what subscription usage actually delivers, adjacent to the SDK-credit billing split documented above.

Try It

1. Verify the current package names against the release log. Read anthropic-sdk-releases-may-2026 for the latest pip install / npm install targets — package names and the .0-vs-.1 adoption rule (skip .0; ship .1) shift faster than this concept page. Tentative install targets: pip install anthropic-agent (Python) and npm install @anthropic-ai/agent-sdk (TypeScript) ^[inferred — confirm against the current SDK release article before running].
2. Walk the CCA-F Agent SDK exercise in certification-technical-reference — define 3-4 tools with detailed descriptions, implement the agentic loop with stop_reason checking, add a PreToolUse hook for threshold-based escalation. The smallest end-to-end build that exercises the SDK’s load-bearing primitives.
3. Read the Managed Agents cookbook side-by-side — anthropic-cookbook-managed-agents-multiagent-outcomes shows the multiagents + outcomes API surface that lands in Python v0.100 / TS v0.95. The cleanest second example after the tool-loop walkthrough.