The Claude Agent SDK is the thing that runs Claude Code, handed to you as a library you can import. You get the same tools, the same agent loop, and the same context management, except now it lives inside your Python or TypeScript program instead of a terminal. You write a few lines, hand Claude a goal like "find and fix the bug in auth.py," and it reads files, runs commands, edits code, and reports back. You never wire up a single tool call yourself.
That's the whole pitch. If you've ever watched Claude Code grind through a refactor and thought "I want that, but firing on a schedule against my repo at 3 a.m.," the Claude Agent SDK is how you get it.
There's also a billing change landing June 15, 2026 that quietly reprices how SDK and headless usage draw from your plan. If you run claude -p in scripts or build anything on the SDK, that part matters more than the API surface, and I'll get to it. First, what you're actually working with.
What the Claude Agent SDK actually is
Anthropic's docs describe it as "Claude Code as a library." The SDK gives you "the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript."
Concretely, you get an agent that already knows how to use tools. Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, all built in. You don't implement tool execution. You declare which tools the agent is allowed to touch, give it a prompt, and stream back the messages as it works.
Here's the entire Python version of a bug-fixing agent:
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)
asyncio.run(main())
The package was called the Claude Code SDK until Anthropic renamed it to the Claude Agent SDK (early 2026, depending on which release notes you read), on the logic that the engine powering Claude Code can power agents that have nothing to do with coding. An email triage agent, a research agent, a nightly compliance check: same loop underneath, none of it about writing code.
If you're migrating from the old package, the imports and names changed; Anthropic keeps a migration guide for that.
claude agent sdk python and claude agent sdk typescript: pick your language
Both languages are first-class. Neither one is a thin wrapper bolted over the other; they're two real SDKs, maintained separately.
For claude agent sdk python, you install with pip install claude-agent-sdk and you need Python 3.10 or later. (If pip complains it can't find a matching distribution, your interpreter is too old. Check with python3 --version.) The source lives at github.com/anthropics/claude-agent-sdk-python.
For claude agent sdk typescript, it's npm install @anthropic-ai/claude-agent-sdk. The TypeScript package bundles a native Claude Code binary for your platform as an optional dependency, so you don't install Claude Code separately. The repo is github.com/anthropics/claude-agent-sdk-typescript. There's also a preview V2 TypeScript interface that drops the async-generator dance for a simpler send/stream session pattern, if multi-turn conversations were giving you grief.
Both want an ANTHROPIC_API_KEY, and both support routing through Amazon Bedrock, Google Vertex AI, and Azure if your shop runs Claude through a cloud provider. One thing worth reading twice from the docs: Anthropic does not allow third-party developers to ship products that log in with a claude.ai account through the SDK unless previously approved. Build on API-key auth.
How it relates to Claude Code (and when to use which)
Claude Code the CLI and the Claude Agent SDK are the same engine with different front doors. The CLI is for you, a human, typing in a terminal. The SDK is for code calling code.
Anthropic's own breakdown is blunt about it. Interactive development and one-off tasks go to the CLI. CI/CD pipelines, custom applications, and production automation go to the SDK. Plenty of teams run both: the CLI for daily hacking, the SDK for the agent that runs in their deploy pipeline. Workflows translate directly between the two because the underlying tools and config are identical.
A couple of capabilities you inherit straight from Claude Code:
Subagents. Your main agent can spawn specialized helpers for focused subtasks, delegate, and collect the results. You define them inline with a description, a prompt, and a tool list, and the agent invokes them through the Agent tool.
Hooks. You can run your own code at lifecycle points: PreToolUse, PostToolUse, SessionStart, and more. Want every file edit appended to an audit log before it happens? That's a five-line PostToolUse hook. This is where the SDK earns its keep in regulated or paranoid environments, because you control exactly what the agent is allowed to do and you get a paper trail.
Sessions. Context persists across exchanges. Claude remembers the files it read and the analysis it did, and you can resume a session later or fork it to try a different approach from the same starting point.
MCP. Connect external systems (databases, browsers, APIs) through the Model Context Protocol, the same servers Claude Code can talk to.
One thing the SDK is not: a hosted service. The agent loop runs inside your process, on your infrastructure, against files on your machine. If you want Anthropic to run the sandbox and the session state for you, that's a separate product called Managed Agents, and the common path is to prototype locally with the Agent SDK, then graduate to Managed Agents for production scale.
claude agent sdk skills: yes, it reads your SKILL.md
If you've written Agent Skills for Claude Code, the SDK runs them unchanged. claude agent sdk skills are the same SKILL.md files, loaded from the same .claude/skills/ directories.
A Skill is a folder with a SKILL.md file inside: YAML frontmatter, a description that tells Claude when to reach for it, and Markdown instructions (plus any supporting files). The SDK discovers skills from the filesystem at startup, reads the metadata, and loads the full content only when a skill actually triggers. Claude decides when to use one based on the description you wrote.
The mechanics, from the Skills SDK docs: set setting_sources=["user", "project"] so the SDK loads from ~/.claude/skills/ and your project's .claude/skills/, then pass skills="all" to enable everything discovered, or a list like skills=["pdf", "docx"] to scope it down.
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
allowed_tools=["Read", "Write", "Bash"],
)
One gotcha: the allowed-tools field inside a SKILL.md only works through the Claude Code CLI. Under the SDK it's ignored, and you control tool access through the main allowedTools option instead. Read that note before you assume a skill's tool restrictions carry over.
The portability is the real story here. A SKILL.md you author once runs in Claude Code, in the SDK, and in other tools that read the open Anthropic Skills format. You're not locked into one runtime.
claude agent sdk vs langgraph
The honest comparison is that they solve different problems, which is why people end up using both.
LangGraph handles orchestration: a directed graph of nodes with conditional edges, sophisticated state management, and an interrupt() primitive for pausing at any node for human approval and resuming from that exact checkpoint. It's model-agnostic and built for stateful, multi-step systems where you want explicit control over what runs when.
The Claude Agent SDK handles execution: how a single agent runs, with which tools, with automatic context management, built for long-running tasks where you'd rather not hand-roll the agent loop. The trade-off is real, though. It's locked to Claude models and a lot lighter on orchestration features.
So the pattern that keeps showing up in 2026 is each LangGraph node powered by a Claude Agent SDK call. LangGraph owns the flow, the SDK executes each step with full agent capabilities. If you're choosing one, pick the SDK when you're all-in on Claude and want the agent loop built for you. Pick LangGraph when you need multi-provider routing and graph-level control. (Comparisons collected here, for the longer version.)
The June 15, 2026 credit change, in plain terms
Now the part that's making heavy Claude Code users nervous.
As of the June 2026 announcement, starting June 15, 2026, Claude Agent SDK usage and claude -p usage stop counting against your normal Claude plan limits. Instead, they draw from a separate monthly Agent SDK credit. Per Anthropic's help article, the amounts are:
- Pro: $20 per month
- Max 5x: $100 per month
- Max 20x: $200 per month
- Team Standard seats get $20, Team Premium and Enterprise Premium seats get $100 and $200 respectively
These credits refresh every month and unused credit does not roll over. Burn it or lose it. The credit is per user, not pooled, so you can't share one teammate's allowance across the org. Anthropic says eligible users get an email with claim instructions before the 15th.
What counts against this credit pool: SDK usage in your own projects, the claude -p headless command, and third-party apps that authenticate through your Claude subscription via the Agent SDK. When the monthly credit runs out, additional SDK usage spills over to usage credits at standard API rates, but only if you've turned usage credits on.
Here's the "which tier am I on, what changes for me" version. For the full credit breakdown across plans, plus the new /usage command for seeing exactly what eats your limits, see Claude Code usage and credits. This section sticks to what the change means if you write SDK code.
If you only ever use Claude Code interactively in the terminal, typing prompts and watching it work, nothing changes. Interactive usage stays on your plan limits exactly as before. This change does not touch you.
If you run claude -p in shell scripts, cron jobs, or CI, that usage moves to the new credit pool on June 15. On Pro that's $20 of SDK work a month before you're paying API rates on top. A nightly job that chews through a repo can clear $20 fast, so check your volume.
If you've built or are building on the Agent SDK, same deal: your programmatic agents draw from the credit pool first, then API rates. Budget accordingly, and remember the credit resets monthly with no carryover, so there's no banking a slow month.
It comes down to this. Interactive Claude Code is metered one way, and automated, SDK-driven Claude is now metered another. If your automation has been quietly riding on your Max plan's generous interactive limits, June 15 is the day that stops being free.
If you want the result without the SDK
The Agent SDK is built for people who write code. That's the audience, and it's a good tool for them.
If what you actually want is to teach Claude one repeatable job (your support-triage process, your weekly report, your exact way of writing release notes) without touching Python or TypeScript, Knack turns a 20-minute interview into a SKILL.md folder that runs in Claude Code, Codex, Cursor, and Gemini CLI. Same open Skills format the SDK reads, no SDK code to write.
If you're shipping agents in 2026, though, the Claude Agent SDK is the most direct path from "Claude Code does this in my terminal" to "Claude Code does this in production." Start with the quickstart, build the bug-fixer, and check your claude -p volume before the 15th. That last part is the one people forget.