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. (As of June 2026. Details may change — see the official Agent SDK docs.)
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 docs, starting June 15, 2026, Agent SDK usage on subscription plans draws from a separate monthly Agent SDK credit, distinct from interactive usage limits. API-key usage follows regular API billing. Check the official docs for the exact policy.
Package names, code, and behavior here reflect the official documentation as of June 2026 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.