Claude Agent SDK vs Claude Code: Same Engine, Different Use Case

The Claude Agent SDK and Claude Code run the same agent loop. One is a library you embed in your application; the other is the interactive terminal tool you type commands into every day. If you have been confused by the naming -- especially since Anthropic renamed the "Claude Code SDK" to "Claude Agent SDK" in September 2025 -- you are not alone. This post gives you the decision table, the billing context, and the migration steps in one place. (Source: Agent SDK overview)

Key takeaways:

  • Both products share the same underlying agent harness: tools, context management, and the feedback loop are identical
  • Use the CLI for interactive development and one-off tasks; use the SDK for CI/CD pipelines, production automation, and custom applications
  • The rename from Claude Code SDK to Claude Agent SDK happened September 29, 2025; migration is a package swap plus one type rename
  • Since June 15, 2026, the SDK draws from a separate credit pool, not your claude.ai subscription

The Short Answer: Same Engine, Two Surfaces

Claude Code is a user-facing CLI product: you open a terminal, type a prompt, and an agent reads files, runs commands, and reports back. The Claude Agent SDK is the same agent loop exposed as a Python library and TypeScript package, so you can drive it programmatically from your own code. (Source: Agent SDK overview)

DimensionClaude Code CLIClaude Agent SDK
InterfaceInteractive terminalPython lib / TS package
Best forDaily development, one-off tasksCI/CD, production apps, automation
Installnpm install -g @anthropic-ai/claude-codepip install claude-agent-sdk or npm install @anthropic-ai/claude-agent-sdk
Billing (since June 15, 2026)Claude.ai subscriptionSeparate SDK credit pool
System prompt defaultClaude Code preset loadedMinimal (since SDK v0.1.0)
SessionsInteractive, local filesystemProgrammatic, stored as JSONL

A useful way to think about it: Claude Code is what a developer uses; the Claude Agent SDK is what developers build with. Many teams use both -- CLI for daily coding, SDK for the pipelines that run in CI. (Source: Agent SDK overview)

Why Anthropic Renamed It

The original name, Claude Code SDK, made the library sound like a tool only for coding tasks. But the same harness powers legal-document agents, research pipelines, and customer-support bots. The rename to Claude Agent SDK took effect on September 29, 2025, with the Anthropic engineering blog post explaining the shift: "The key design principle behind the Claude Agent SDK is to give your agents a computer, allowing them to work like humans do." (Source: Anthropic Engineering blog)

For TypeScript projects, the npm package moved from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk. For Python, claude-code-sdk became claude-agent-sdk and the main options type was renamed from ClaudeCodeOptions to ClaudeAgentOptions. No logic changed; only the surface names did.

The Billing Split (June 15, 2026)

Before June 15, 2026, developers building on the SDK could draw against the same credit pool attached to a claude.ai Pro or Team subscription. Anthropic split these into separate pools on June 15: the SDK now draws from API credits, while the Claude Code CLI continues to run on the subscription. Inference: based on Anthropic's June 15, 2026 billing change. (Source: Agent SDK migration guide)

The practical impact: if your team was using a shared Pro subscription to power both a production agent pipeline and daily developer usage, you now need an explicit API key and API credits for the SDK workloads. The cost structure is the same per-token pricing as the Anthropic API; the change is administrative, not a price increase. For context on current pricing tiers, see Claude API Pricing: Haiku, Sonnet 4.6, and Opus 4.8 for Agent Builders.

When to Use Claude Code CLI

The CLI is the right choice when the goal is interactive exploration or a quick one-off task. You get the full agent loop -- read files, run commands, edit code, search the web -- through a conversational interface with no additional code to write. Flags like --dangerouslySkipPermissions and --allowedTools let you tune permissions without touching a config file.

Common CLI scenarios:

  • Refactoring a module while you review the output
  • Running a one-time migration script
  • Debugging a production issue in a sandboxed environment
  • Generating documentation from a codebase during a sprint

The CLI loads ~/.claude/settings.json, project .claude/ files, and CLAUDE.md automatically, so your custom skills and preferences carry over without any setup. (Source: Agent SDK overview)

When to Use the Claude Agent SDK

The SDK is the right choice any time the agent needs to run without a human in the terminal -- a scheduled job, a CI step, an application endpoint, or a long-running background task. The library gives you:

  • Programmatic control: pass a prompt and options, iterate over the returned messages, handle tool-result events
  • Custom tool hooks: PreToolUse and PostToolUse callbacks for audit logging, approval gates, or cost throttling
  • Subagent spawning: define specialized agents in AgentDefinition objects and let the main loop delegate to them
  • MCP server attachment: connect third-party MCP servers by passing a mcpServers config dict (Source: Agent SDK overview)
  • Transport flexibility: supports Bedrock, Vertex AI, Azure AI Foundry, and the Anthropic API via environment variables

Operator note (first-hand): Installing @anthropic-ai/claude-agent-sdk@0.2.0 and running a minimal TypeScript query loop (for await (const message of query({ prompt: "List files here", options: { allowedTools: ["Bash", "Glob"] } })) { ... }) produces the same tool-call stream as running claude -p "List files here" --allowedTools Bash,Glob from the CLI. The output is identical; what differs is that the SDK version runs inside your Node process and exposes the message stream as an async iterable you can inspect, filter, or pipe to your own logging.

The SDK is also the right path when you want to suppress the Claude Code system prompt. Starting with SDK v0.1.0, the library defaults to a minimal system prompt instead of loading Claude Code's CLI-focused instructions, giving you a clean slate for building non-coding agents. (Source: Agent SDK migration guide)

Migrating: ClaudeCodeOptions to ClaudeAgentOptions

If you are on claude-code-sdk (Python) or @anthropic-ai/claude-code (TypeScript), the migration is mechanical:

TypeScript:

npm uninstall @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk

Update all imports from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk. No other code changes are required unless you relied on the default system prompt behavior.

Python:

pip uninstall claude-code-sdk
pip install claude-agent-sdk

Rename ClaudeCodeOptions to ClaudeAgentOptions everywhere it appears. The two types have identical fields; only the name changed. (Source: Agent SDK migration guide)

The one breaking change to watch: SDK v0.1.0 no longer loads Claude Code's system prompt by default. If your agent depended on that preset, pass it explicitly:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
prompt="...",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}
),
):
...

This also means Python SDK 0.1.59 and earlier treated setting_sources=[] the same as omitting it -- upgrade before relying on that flag for CI isolation. (Source: Agent SDK migration guide)

For a full comparison against the competing framework, see Claude Agent SDK vs OpenAI Agents SDK. For the $200 per-developer credit cap that predates the June 15 billing split, see Claude Agent SDK $200 cap: dev impact guide.

FAQ

Is the Claude Code SDK deprecated?

The package @anthropic-ai/claude-code and claude-code-sdk (Python) are deprecated in favor of the renamed equivalents. They may still install and run, but Anthropic's active development and documentation are now on @anthropic-ai/claude-agent-sdk and claude-agent-sdk. Migrate when you next update dependencies.

Is the Claude Agent SDK the same as Claude Code?

They share the same agent engine -- the same tools, agent loop, and context management. Claude Code is the interactive CLI; the Claude Agent SDK is the library form of that engine for embedding in your own applications. Same internals, different interface.

Why use the Claude Agent SDK instead of the Anthropic Messages API?

The Anthropic Client SDK (Messages API) gives you raw model access: you send a prompt, you get a completion, and you implement any tool loop yourself. The Agent SDK gives you Claude with built-in tool execution already wired -- Read, Write, Edit, Bash, WebSearch. If you want autonomous multi-step execution without writing a tool loop, the Agent SDK is the shorter path. (Source: Agent SDK overview)

Does the Claude Agent SDK work with Amazon Bedrock or Google Vertex AI?

Yes. Set CLAUDE_CODE_USE_BEDROCK=1 and configure AWS credentials for Bedrock, or CLAUDE_CODE_USE_VERTEX=1 and Google Cloud credentials for Vertex AI. Azure AI Foundry is also supported via CLAUDE_CODE_USE_FOUNDRY=1. (Source: Agent SDK overview)

Related coverage

References