Claude Agent SDK vs Claude Code: What's the Difference (and When to Use Each)

Claude Agent SDK vs Claude Code: What's the Difference (and When to Use Each)

Short answer: Claude Code is Anthropic's interactive coding agent, the one you run in a terminal or IDE and talk to like a very capable pair programmer. The Claude Agent SDK is the framework underneath it, packaged so you can build your own agents on the same engine. Anthropic's own description is blunt about it: the SDK lets you "build production AI agents with Claude Code as a library."

They used to be one and the same product on paper. Anthropic shipped a "Claude Code SDK" alongside the CLI, then renamed it to the Claude Agent SDK to make a point: the toolkit was never just for coding tasks. It's the permission system, the tool-use loop, the subagent orchestration, and the context management that power Claude Code, available to wire into whatever you're building, support bots, research agents, internal ops tools, QA pipelines, anything that needs to plan, call tools, and decide when a task is done.

This post breaks down what each one actually is, where the line sits, and which one fits your project. If you've read "Claude Code SDK" in older docs or tutorials, that's the same product under its old name; the migration guide below covers what changed.

What Claude Code actually is

Claude Code is the product you install and run directly: a command-line agent (plus VS Code and JetBrains extensions, and a desktop app) that reads your codebase, edits files, runs shell commands, and iterates until a task is done. You point it at a repo, describe what you want, and it works the way a senior engineer would work through your terminal, asking permission before risky actions unless you've configured it otherwise.

It's built for one primary use case: a human developer, working interactively, on a coding task. Sessions are conversational. You course-correct mid-task. Output is a diff, a passing test, a shipped PR.

What the Claude Agent SDK actually is

The Claude Agent SDK is a library, available for TypeScript and Python, that gives you programmatic access to the same agent harness Claude Code runs on. Instead of a person typing into a terminal, your own application code drives the session: you send a task, the SDK runs Claude through its plan-call-tools-decide loop, and you get structured results back.

Concretely, the SDK exposes the pieces Claude Code assembles for you automatically:

• The agent loop. How Claude plans a task, calls tools, and decides when it's finished, exposed as an API instead of a terminal session.
• Tool use and custom tools. Claude can call your own functions and APIs through an in-process MCP server, on top of whatever external MCP servers you connect.
• Subagents. Spin up isolated sub-tasks with their own context and instructions, useful for running work in parallel without one giant context window doing everything.
• Skills and plugins. Package reusable instructions, hooks, and tool sets that your agent sessions can discover and load.
• Permissions and hooks. Declarative allow/deny rules plus hook points to intercept and control what the agent is allowed to do, before it does it.
• Structured output. Get validated JSON back from a multi-turn agent run using JSON Schema, Zod, or Pydantic, instead of parsing free text.
• Streaming. Real-time text and tool-call events as they happen, for building a responsive UI on top.
• Checkpointing. Track file changes during a session and roll back to any previous state.
• Cost tracking and observability. Token usage, prompt caching, and OpenTelemetry export for production monitoring.
• Deployment guidance. Anthropic documents subprocess architecture, session persistence, and multi-tenant isolation for running the SDK in Docker, Kubernetes, or a sandboxed environment at scale.

None of that requires you to reimplement an agent loop from scratch on top of the raw Claude API. You get Claude Code's engineering, just embedded in your product instead of a terminal window.

The core difference, side by side

When to use Claude Code directly

Reach for Claude Code, no SDK involved, when:

• You're a developer who wants an agent that reads and edits your codebase interactively, in a terminal or IDE.
• The work is exploratory: refactors, bug hunts, writing tests, reviewing a PR, the kind of task where you're steering mid-session.
• You don't need to embed agent behavior inside a product you're shipping to other people. You're the end user.

If your team's actual bottleneck is getting more engineers proficient with Claude Code itself, rather than building on top of it, see our guide on setting up Claude Code for a team or, if you're evaluating outside help, when to hire a Claude Code consultant.

When to use the Claude Agent SDK

Reach for the SDK when the agent isn't for you, it's for your product or your users. Typical cases:

• Customer-facing agents. A support agent, a research assistant, an onboarding bot, anything where an end user interacts with an agent through your own UI, not a terminal.
• Unattended or scheduled agents. Batch jobs, data pipelines, QA sweeps, anything that runs on a trigger without a human watching.
• Multi-agent systems. If your architecture needs several specialized agents coordinating on a task, the SDK's subagent support handles context isolation and parallel execution without you building that plumbing yourself. Our post on building a multi-agent system with Claude goes deeper on this pattern, and our roundup of Claude Code sub-agents covers the subagent side specifically.
• Products you're shipping to customers. The SDK's license (Anthropic's commercial terms) explicitly covers using it to power products and services you sell to your own end users, not just internal tools.
• Anything needing production controls. Permission rules, hooks that block or approve specific tool calls, cost tracking, and OpenTelemetry traces, the kind of guardrails you need before an autonomous agent touches production data.

If part of that build involves giving your agent access to outside systems, databases, ticketing tools, internal APIs, that's the same MCP layer Claude Code uses. Our MCP protocol explainer and list of best Claude Code MCP servers cover how that connection layer works if you're new to it.

Can you use both?

Yes, and most teams building agent products end up doing exactly that. Engineers use Claude Code directly to write and iterate on the application code, including the code that calls the Claude Agent SDK. The SDK app itself, once shipped, is a separate running system with its own users, who never see Claude Code at all. One is a development tool. The other is what you built with it.

Common mistakes people make with this distinction

Assuming the Agent SDK is only for coding agents. It isn't, and Anthropic renamed it specifically to stop that assumption. Support, research, ops, and data-processing agents are all standard SDK use cases now.

Trying to rebuild Claude Code's engine on the raw Claude API instead of using the SDK. The agent loop, permission system, and subagent orchestration are non-trivial to get right. The SDK ships that work done.

Calling a shipped product "Claude Code" when it's SDK-built. Anthropic's branding guidelines are specific here: SDK-based products should carry their own branding, not present themselves as Claude Code. "Powered by Claude" or "Claude Agent" in a menu label are fine; naming your product "Claude Code" is not.

FAQ

Is the Claude Agent SDK the same as the old Claude Code SDK? Yes. Anthropic renamed the Claude Code SDK to the Claude Agent SDK to reflect that it supports agents well beyond coding tasks. If you find older tutorials referencing the Claude Code SDK, the code generally still applies; check Anthropic's migration guide for anything that changed in the rename.

Do I need to know Claude Code to use the Claude Agent SDK? No. They share an engine, not a required learning path. You can go straight to the SDK docs and build without ever running the Claude Code CLI, though using Claude Code yourself is a fast way to get a feel for how the agent loop behaves before you wire it into your own app.

What languages does the Claude Agent SDK support? TypeScript and Python, both with full API references and example projects from Anthropic.

Can the Claude Agent SDK call my own internal tools and APIs? Yes, through an in-process MCP server for custom tools you define, plus support for connecting external MCP servers for tools that already exist as MCP integrations.

Is the Claude Agent SDK free? The SDK itself is free to use; you pay for the underlying Claude API usage (tokens) the same way you would calling the API directly. Check Anthropic's current pricing page for rates, since those change independently of the SDK.

Can I build a commercial product with the Claude Agent SDK? Yes. Anthropic's commercial terms of service explicitly cover using the SDK to power products and services you sell to your own customers, not just internal tooling.

Does the Claude Agent SDK replace the Claude API? It sits on top of it. The SDK adds the agent loop, tool orchestration, permissions, and subagent handling around the underlying API calls, so you're not reimplementing that layer yourself. If all you need is a single request-response call with no tool use or multi-step planning, the plain API may be all you need.

Where this fits if you're building

If you're evaluating whether to build a custom agent on the Claude Agent SDK versus assembling one from scratch, that's most of the design work we do for clients: agent architecture, tool and permission design, and production deployment. See our AI agent development services if you want a second set of eyes on the build before you commit engineering time to it.

---

Sources: Claude Agent SDK overview, Claude Agent SDK migration guide, Claude Code documentation, Anthropic commercial terms of service