Claude Agent SDK vs Claude Code: when to use which

Anthropic ships two main developer-facing surfaces for building agents:

1. Claude Code, a CLI you install with npm i -g @anthropic-ai/claude-code and run from your terminal
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
• Cost model: both bill against the same Anthropic Console tokens

What doesn’t transfer

• Slash commands: Claude Code-only (they’re a CLI affordance)
• Hooks (as defined in .claude/settings.json): Claude Code-only. The Agent SDK has its own pre/post-hook callbacks but the configuration shape is different.
• The terminal UX: obviously

A concrete Australian example

At Boring Ventures we use Claude Code for:

• Daily content production (this article was drafted in Claude Code)
• the nightly inventory audits run via cron (headless mode)
• Lead Gen Empire deploys + audits
• Drafting client quotes + 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 90% of Australian SMB 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, 30-second version)

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

const agent = new Agent({
 model: 'claude-sonnet-4-6',
 systemPrompt: 'You are an Australian small business operations agent. Australian English. AUD pricing.',
 tools: ['filesystem', 'bash', 'webSearch'],
 permissions: { allow: ['Read', 'Write(*.csv)'], deny: ['Bash(rm:*)'] },
})

const result = await agent.run({
 prompt: 'Read sales.csv and tell me the top 5 SKUs by revenue this month.',
 maxTurns: 20,
})

console.log(result.text)
console.log(`Cost: ${result.usage.estimatedCostAUD} AUD`)

That’s the entire surface for a one-shot agent run. Streaming, multi-turn, tool-use callbacks all expose with similar shape.

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.