Claude Agent SDK: Claude Code, but called from your code

TL;DR pip install claude-agent-sdk (or npm install @anthropic-ai/claude-agent-sdk), import query, pass a prompt and the list of allowed tools, and you get the same agent that runs in your terminal — programmable. CI/CD, cron, API, whatever. Under the hood: the agent loop, the built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch...), the skills in ~/.claude/, hooks, subagents, MCP, sessions with resume/fork. It's not the Client SDK (where you implement the tool loop yourself). It's the full agent running in your process. A billing note: Anthropic announced a separate monthly Agent SDK credit for June 15, 2026, but walked it back before it shipped; for now SDK usage still draws from your subscription limits (the full story).

If you've been using Claude Code in the terminal for a while, here's the confusion saver: Claude Agent SDK and Claude Code SDK are the same SDK. Anthropic renamed it during 2026 — Google's PAA is still full of people asking "What is the difference between Claude Code and Claude Agent SDK?". The real difference is the interface: in your terminal you call claude, in your code you call it as a library.

Under the hood it's the same agent loop that runs when you type claude in your terminal: reads files, runs commands, edits code, manages context. The library exposes the primitives you already know (skills, hooks, subagents, MCP, permissions) as arguments to the query function.

Hello world

Python, with Read + Edit + Bash allowed:

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())

TypeScript equivalent:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

That's it. You don't implement the tool loop. You don't serialize tool_use or tool_result. Claude handles all of it inside the library.

Setup

1. Install the SDK.

pip install claude-agent-sdk                      # Python
npm install @anthropic-ai/claude-agent-sdk        # TypeScript

The TypeScript SDK bundles a native Claude Code binary, so you don't need to install Claude Code separately.

2. Configure your API key.

export ANTHROPIC_API_KEY=your-api-key

Other supported auth providers: Amazon Bedrock (CLAUDE_CODE_USE_BEDROCK=1), Google Vertex AI (CLAUDE_CODE_USE_VERTEX=1), Azure AI Foundry (CLAUDE_CODE_USE_FOUNDRY=1), Claude Platform on AWS (CLAUDE_CODE_USE_ANTHROPIC_AWS=1).

Claude Code (CLI) vs Agent SDK: when to use which

Same capabilities, different surface. Anthropic's own table:

"Many teams use both: CLI for daily development, SDK for production." — docs.

What you can plug in (same as local)

Skills, slash commands and CLAUDE.md load by default from .claude/ and ~/.claude/. To restrict sources, pass setting_sources in your options.

The SDK ≠ Client SDK

The classic mix-up. The Anthropic Client SDK gives you direct API access: you send prompts and you implement the tool loop. The Agent SDK ships with it built-in:

# Client SDK — you write the loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK — Claude handles tools
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

If you find yourself writing while response.stop_reason == "tool_use", you're in the wrong SDK.

Cost and billing

Today, Agent SDK usage on a subscription plan counts against your subscription limits, like the rest of Claude Code. Anthropic announced a separate monthly Agent SDK credit for June 15, 2026 (per-plan amounts, opt-in, no rollover), but walked it back before it shipped; it may return reworded and with advance notice. The full story is in the Agent SDK credit tip. Official detail in the pricing notice.

If you use the SDK with an API key (not a subscription plan), it counts as regular API: tokens billed to your account.

Pairs well with

• GitHub Actions — the @claude PR-review action runs on top of the Agent SDK. Knowing this lets you extend it.
• Subagents — the pattern you already used locally, now via agents={}.
• Plugins — loadable programmatically via the plugins option.
• Slash commands cheat sheet — everything you invoke with / is also invokable from the SDK.

Official docs: Agent SDK overview · Python SDK · TypeScript SDK