Claude Agent SDK vs Claude Code: when to use which

Two of Anthropic’s ways to build agents share the same engine (Anthropic also offers the plain Client SDK and hosted Managed Agents, which work differently):

1. Claude Code, a CLI you install with Anthropic’s installer (or npm i -g @anthropic-ai/claude-code) and run from your terminal or the desktop app
2. Claude Agent SDK, a library you pip install claude-agent-sdk (or npm i @anthropic-ai/claude-agent-sdk) into your own application

They’re built on the same engine. The question is which interface you want.

Use Claude Code when

• You’re the operator, you’re the one prompting, watching outputs, approving actions
• You want the experience of pair-programming with an AI assistant
• The agent runs on your machine, your laptop, or your VPS as a scheduled task
• You’re doing ad-hoc business operations (data analysis, content drafting, file editing)
• You want zero infrastructure overhead, claude and you’re working

Use the Claude Agent SDK when

• You’re building software that other people use (a SaaS, a customer-facing tool, an embedded assistant)
• The agent runs in your application’s backend, triggered by user actions or events
• You want fine-grained control over the loop, when to add tools, when to stop, what to do with intermediate output
• You’re building a multi-tenant system (each user gets their own agent context)
• You need to integrate with your existing telemetry, auth, logging stack

What transfers between them

• MCP servers: every MCP server works in both
• Skills: a SKILL.md works in either (with minor packaging differences)
• Tool patterns: the shape of tool calls is identical
• Prompt engineering: everything you learn about prompting Claude transfers directly
• Configuration: the SDK loads skills, commands and CLAUDE.md memory from your project’s .claude folder, the same as Claude Code

What’s different

• Billing and login: Claude Code can run on a Claude subscription or an API key. Agents you build on the SDK use API key authentication; Anthropic doesn’t allow third-party products to offer claude.ai login unless approved.
• Hooks: the SDK supports hooks, but you can write them as callbacks in your own code as well as in settings files.
• The terminal interface: Claude Code only.

A concrete Australian example

At Boring Ventures we use Claude Code for:

• Daily content production (this article was drafted in Claude Code)
• Building and maintaining the scheduled jobs behind our skincare brand’s inventory system
• Building, deploying and checking the Lead Gen Empire websites
• Drafting quotes and reports

We’d use the Claude Agent SDK to build:

• A customer-facing agent inside a SaaS we ship (none yet, but it’s where we’d reach for it)
• An embedded support agent inside a client’s web app
• A multi-tenant ops automation tool

For most Australian small-business operators, the answer is “use Claude Code, skip the SDK until you’re literally building software for sale.” The SDK is overkill if you’re the operator and there’s no end-user agent product involved.

What the SDK looks like (TypeScript)

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

for await (const message of query({
  prompt: 'Read sales.csv and tell me the top 5 SKUs by revenue this month.',
  options: {
    allowedTools: ['Read', 'Glob'],
    maxTurns: 20,
  },
})) {
  if (message.type === 'result' && message.subtype === 'success') {
    console.log(message.result)
  }
}

query() runs the same agent loop as Claude Code and streams messages back as it works; the final result message carries the answer. Check the Agent SDK documentation for the current options before you build on it.

Bottom line

Build with Claude Code first. Move to the Claude Agent SDK only when you’re explicitly building agent-shaped software that ships to other people. The SDK is the right tool for the right job; for most Australian SMB workflows, Claude Code is the right job.