The Claude Agent SDK is a Python and TypeScript library that lets you call the same agent loop, tools, and context management that power Claude Code from your own code. Instead of typing into a terminal, you call a function and embed the agent in a product, an internal tool, or an automation pipeline. This guide covers how it differs from the regular client SDK, how the agent loop works, starter code, and key options, based on the official docs. (Details may change — see the official Agent SDK docs.)
🟢 Model references match the current lineup · model notice · Fable subscription
Fable 5 and 5.1 subscription (updated November 1, 2026): Claude Fable 5.1, released September 1, 2026, is the current Fable model and Fable 5 is now legacy. Plan terms are the same for both — Max, Ultra, and Team Premium plans include Fable at up to 50% of the weekly usage limit; Pro and Team Standard use usage credits ($10/M input, $50/M output tokens). The one-time $100 credit applied only to the Fable 5 transition and is not offered for 5.1. Some coding and debugging requests may be answered by an Opus model due to a security classifier (both models). See the Fable 5.1 guide and the Fable 5 availability guide for details.
How it differs from the client SDK
The regular client SDK is a thin wrapper around the Messages API, so with tool use you implement the loop yourself: check the response, execute the tool, send the result back. The Agent SDK takes over that whole loop. When Claude picks a tool, the SDK executes it locally and feeds the result back automatically, repeating until the task completes. In short: the client SDK is a model-calling library; the Agent SDK is an agent-running library.
Note that the Agent SDK is the renamed successor of the “Claude Code SDK.” Migration is an import change: Python claude_code_sdk → claude_agent_sdk, TypeScript @anthropic-ai/claude-code → @anthropic-ai/claude-agent-sdk (and ClaudeCodeOptions → ClaudeAgentOptions).
Install and your first agent
The packages are claude-agent-sdk for Python and @anthropic-ai/claude-agent-sdk for TypeScript. The main entry point is query() — an async generator that takes a prompt and options and streams messages back.
# pip install claude-agent-sdk
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # Claude reads the file, finds the bug, edits it
asyncio.run(main())While the loop runs, each iteration yields a message: Claude’s reasoning, a tool call, a tool result, or the final outcome. Each query() call starts a fresh session with no memory of previous interactions; for multi-turn conversations, use the stateful client interface instead.
Claude Code features, programmatically
The Agent SDK exposes Claude Code’s building blocks in code.
- Built-in tools — file read/write/edit, search (Glob, Grep), shell (Bash), web access. No tool-execution code to write.
- MCP servers — attach external service tools to your agent. See what MCP is.
- Permission control — limit what the agent can do with
allowed_tools, deny rules, and permission modes. The rule system shares concepts with Claude Code permissions. - Hooks, subagents, skills — insert custom logic around tool runs (hooks) and split work across subagents, all supported in the SDK.
When to use which
For plain text generation, classification, or one-shot calls, the client SDK is enough and lighter. For tasks where the model decides multiple steps on its own across files, commands, and the web — code-repair bots, research agents, CI automation — the Agent SDK removes the burden of implementing the loop. Many teams pair them: Claude Code CLI for daily development, the Agent SDK for production automation.
On cost (per the official help article as of October 31, 2026): Anthropic announced on May 14 that subscription-plan Agent SDK and claude -p usage would move to a separate monthly credit, then paused that change on June 15. Since an October 7, 2026 update, Claude Max and Team plans include monthly API credits. The credits apply to the Claude API, Claude Managed Agents, the Agent SDK, and claude -p when you run them with an API key from your linked Claude Console organization; when you sign in with your Claude plan, the Agent SDK and claude -p still draw from your subscription limits. The help article does not state the credit amount or detailed terms — check the official help article and its linked "Monthly API credits for Max and Team plans" page (Pro is not mentioned). API-key usage follows regular API billing; note that the official docs state third-party developers may not offer claude.ai login (subscription limits) in their products without prior approval, so use API-key authentication for anything you ship.
Package names, code, and behavior here reflect the official documentation as re-checked on September 9, 2026 (overview, quickstart, migration guide) and may change with SDK versions. For the full option list and latest changes, see the official Agent SDK docs. This site is not an official Anthropic site.
Related articles
- Getting Started with the Claude SDK (Python & TypeScript)
- Claude SDK Streaming: SSE Events, Real-time Output & Error Recovery
- Claude Opus 4.7: The Complete Guide to New Features and Specs
- Claude Code Installation Guide: native vs npm, Windows Included
- How to Write Prompts for Claude: 6 Core Principles from the Official Docs