Skip to main content
Using Claude

Claude Agent SDK Guide: Claude Code's Agent Loop in Code

Call the agent loop and tools that power Claude Code from Python or TypeScript - the Agent SDK explained from the official docs.

ByUpdated

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
🟢 Model references match the current lineup · Claude Opus 5 / Claude Sonnet 5 / Claude Haiku 4.5 (higher tier: Claude Fable 5.1). This notice changes only when Anthropic ships a new model.

Fable 5 and 5.1 subscription (updated September 7, 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 and Team Premium plans include Fable at up to 50% of the weekly usage limit; Pro and Team Standard use usage credits (

🟢 Model references match the current lineup · Claude Opus 5 / Claude Sonnet 5 / Claude Haiku 4.5 (higher tier: Claude Fable 5.1). This notice changes only when Anthropic ships a new model.
0/M input, $50/M output tokens). The one-time
🟢 Model references match the current lineup · Claude Opus 5 / Claude Sonnet 5 / Claude Haiku 4.5 (higher tier: Claude Fable 5.1). This notice changes only when Anthropic ships a new model.
00 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.

The agent loop — the SDK runs it for you Prompt "Fix the bug in auth.py" Claude decides next action Tool runs Read, Edit, Bash… results fed back — repeats until done - When no more tool calls remain (task done), the final result is produced and the loop ends. - Includes the same built-in tools as Claude Code: file read/edit, search, shell, web access. - You never manage this loop — just consume messages with async for.

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.

Client SDK vs Agent SDK Client SDK - Wrapper around the Messages API - You implement the tool loop - One request, one response; fine control - Chatbots, one-shot calls, custom pipelines repeat client.messages.create(...) Agent SDK - Claude Code’s agent loop built in - Tools run automatically, looped - Built-in tools (Read, Edit, Bash, web) - Autonomous agents, automation, products async for m in query(prompt=...) Both are officially supported — pick by use case; many teams use both

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: on May 14, 2026 Anthropic announced that from June 15 Agent SDK and claude -p usage on subscription plans would move to a separate monthly Agent SDK credit — but it paused that change on June 15. Per the official help article (updated June 16), nothing has changed for now: Agent SDK, claude -p, and third-party app usage still draw from your subscription's usage limits, and the announced monthly credit is not available. Anthropic says it will give advance notice before any revised plan takes effect. 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.

See also: Claude SDK Streaming Guide

Was this helpful?

Keep reading

Claude SDK Error Handling and Retries: APIError Types, max_retries, and Timeout Config

A practical guide to how the Claude API's Python and TypeScript SDKs classify errors into typed exceptions, which failures get retried automatically, and how to customize retry and timeout behavior.

35

Is Claude Fable 5.1 Nerfed? The Real Reasons Behind the Complaints

Some users feel Claude Fable 5.1 got weaker overnight. Here's what Anthropic's own documentation says is actually happening, and how to check your settings.

1

Back on Claude Fable? Here's What to Check First

If you tried another AI and came back to Claude Fable, here's how to switch to Fable 5.1, what changed in subscription terms, and how the automatic fallback to Opus works.

5

Claude billing, subscription and usage limits — a situation-by-situation guide (2026)

Payment failures, cancel and refund, usage limits, plan choice, Claude Code and API costs — one page that tells you which article to read for each situation.

7