Anthropic has drawn a sharp line between two products that share the same engine but serve completely different purposes: Claude Code, an interactive terminal tool, and the Claude Agent SDK, a library for embedding agents into production software. The distinction matters because developers have been confused about which to use, and the choice affects everything from workflow to billing.

What's the Actual Difference Between Claude Code and the Agent SDK?

Both products run the same agent loop and share the same underlying tools, but they answer different questions about who controls the agent. Claude Code is the interactive product you drive from a terminal, where a human is at the keyboard making decisions turn by turn. The Claude Agent SDK is that same harness packaged as a Python and TypeScript library you embed in your own software, where your code orchestrates the agent programmatically.

The decision line is straightforward: use Claude Code when a human is exploring a codebase, pairing on a refactor, or reviewing what an agent did before merging. Use the Agent SDK when software is at the keyboard, such as in a continuous integration (CI) job, a Slack bot, a product feature, or a pipeline that calls query() and processes the message stream.

Anthropic's own documentation reinforces this split. As the source notes, "Many teams use both: CLI for daily development, SDK for production." This dual-use pattern is becoming standard practice among developers who want interactive flexibility during development but need programmatic control in deployed systems.

How to Choose Between Claude Code, the Agent SDK, and Managed Agents?

• Claude Code (CLI): Use this interactive terminal product when you need human-driven exploration and decision-making. It includes features like permission prompts, plan approval, and a dashboard for background sessions. Best for daily development work and one-off tasks.
• Claude Agent SDK: Choose this library when you're building software that orchestrates agents programmatically. It supports CI/CD pipelines, custom applications, and production automation. Starting June 15, 2026, SDK usage draws from a separate monthly Agent SDK credit, distinct from interactive plan limits.
• Claude Managed Agents: Select this hosted option when you want neither the terminal nor the process. Anthropic runs the agent loop and sandbox per session, and your app communicates over a REST API, eliminating infrastructure management on your end.

What Technical Details Should Developers Know?

The two products handle subagents differently. In Claude Code, subagents are markdown files stored in a.claude/agents/ directory. In the Agent SDK, the recommended approach uses the agents parameter on query(), which accepts a dictionary of AgentDefinition objects. Each definition includes a required description and prompt, plus optional parameters like tools, disallowedTools, model (with aliases including fable, opus, sonnet, haiku, and inherit), skills, memory, mcpServers, maxTurns, background, effort, and permissionMode.

One important security detail: the SDK documentation states that Anthropic does not allow third-party developers to offer claude.ai login or rate limits in their products unless previously approved. This matters if you're building a product for end users, as it affects how authentication flows work.

For larger orchestration tasks, the TypeScript SDK (version 0.3.149 and later) exposes a Workflow tool that coordinates dozens to hundreds of agents. The runtime caps runs at 16 concurrent agents and 1,000 agents total, which bounds the cost of a runaway script. Intermediate results are held in script variables instead of Claude's context window, enabling more complex multi-step automation.

How Does Billing Change Between These Options?

Claude Code operates under interactive plan limits tied to your subscription. The Agent SDK, however, introduced a separate billing model starting June 15, 2026. SDK and claude -p usage on subscription plans now draws from a new monthly Agent SDK credit, separate from interactive limits. This separation allows teams to budget differently for development versus production workloads.

For teams managing multiple agents or complex workflows, this billing distinction is significant. A team might use Claude Code freely during development but incur Agent SDK credits only when agents run in production or via scheduled routines. Understanding this split helps teams forecast costs more accurately.

What About Scheduling and Background Sessions?

Claude Code includes Routines, which allow you to schedule agent work using schedule, API, and GitHub triggers on Anthropic-managed cloud infrastructure. The Agent SDK, by contrast, gives you flexibility to use your own cron jobs, message queues, or webhooks to call the SDK or claude -p commands.

For background session management, Claude Code offers a dashboard that groups sessions by status: needs-input, working, and completed. Sessions run under a separate supervisor process, so they survive closing the terminal, machine sleep, and auto-updates. This feature is available in Claude Code version 2.1.139 and later as a research preview.

The Agent SDK, meanwhile, exposes the Workflow tool for TypeScript users, enabling orchestration that moves into a JavaScript script the runtime executes outside the conversation. This approach suits teams that need programmatic control over multi-agent coordination and want results held in script variables rather than in Claude's context.