Claude Agent SDK vs API vs Claude Code: Which to Use

#Where these three actually differ (from a delivery perspective)

While official documentation describes each tool clearly, when standing in the shoes of someone who has to choose and deliver, I find that two simple questions are enough to set them apart:

1. Who writes the agent loop? — meaning the loop of "Claude calls tool → we execute tool → return results → Claude decides next step," along with context management during long conversations. Let's call this the harness.
2. Who manages the infrastructure to run it? — the process, machine, sandbox, and session state storage. Let's call this the deployment.

Mapping them along these two axes:

• Claude API (Messages API with Tool Runner) — You define the tools, the SDK (or you) handles the loop, and you self-host. There are no built-in tools or sandboxes. This is the "least magical" level: you control every step, but you must wire everything yourself.
• Claude Agent SDK — Claude Code packaged as a library (claude_agent_sdk for Python, @anthropic-ai/claude-agent-sdk for TypeScript). It carries the exact same harness as Claude Code: the agent loop, context management, and the built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch…), along with hooks, subagents, permissions, and sessions. You only provide the prompt and configuration, but you still self-host it (runs inside your own process).
• Claude Code — The same harness, but as an interactive CLI to type in the terminal. Same capabilities as the Agent SDK, just a different interface.
• Managed Agents — Anthropic handles both the harness and the deployment: running the agent loop on Anthropic's infrastructure and provisioning a sandbox for each session. You send events and receive results via REST.

The most common point of confusion: Agent SDK is not the Tool Runner of the Claude API. Tool Runner (client.beta.messages.tool_runner in the anthropic / @anthropic-ai/sdk library) is just a thin helper that runs the loop for tools you define yourself—it doesn't have built-in tools or filesystem access. The Agent SDK (claude-agent-sdk) is the entire engine of Claude Code. They are two different packages operating at two different layers.

The ladder from high control to high convenience:

As you move down, you delegate more responsibilities (first the agent loop, then the entire infrastructure) to Anthropic—trading control for convenience.

#Before choosing: Do you actually need an agent?

The most frequently overlooked question: An agent (multi-step, self-invoking tools, autonomous decision-making) consumes significantly more tokens and is less predictable than a direct request. I only escalate a task to an "agent" when it meets all four criteria:

• Multi-step & hard to specify upfront — like "translate this design doc into a PR" rather than "extract the title from this PDF."
• Cost-justified — the outcome outweighs the higher cost and latency.
• Feasible for Claude — matching the model's strengths.
• Recoverable from errors — accompanied by tests, review steps, or rollbacks to catch mistakes.

If any of these is missing, step down to a simpler approach: a single Claude API request (classification, summarization, extraction, Q&A) or a programmatically orchestrated workflow. This is rarely mentioned in generic introductory articles, but from a delivery standpoint, it saves the most resources: don't build an agent for a task that can be solved with a single SQL query.

#Decision Matrix by Delivery Scenario

This is the matrix I actually use when scoping a project. The primary axis is the delivery scenario, not abstract technical specifications—because the deciding factor is usually "who will operate this once I hand it over," rather than "which one has more features."

To summarize the matrix: internal automation on your infra → Agent SDK; embedded in your product with control → Claude API; quick interactive work → Claude Code; hands-off infrastructure → Managed Agents.

#A few traps you only see in production

• The Agent SDK is surprisingly simple to invoke. At its core, it's just query(prompt, options) returning a message stream. But "simple to run" does not mean "simple to put in production"—see the checklist below.
• Auth: You cannot use claude.ai login for third-party products. The Agent SDK in your app must use an API key (or Bedrock/Vertex/Foundry). This means every client or agent session incurs token costs you need to monitor from day one; don't wait until the end of the project to realize this.
• Session state in the Agent SDK is a JSONL file on your filesystem. Very convenient for resuming/forking, but at handover, you must answer: who backs it up, who deletes it, and how long is it kept? For Managed Agents, state is kept in the event log hosted by Anthropic—trading convenience for control.
• Branding restrictions. A product built on the Agent SDK must not be named or branded as "Claude Code." It sounds minor, but it's something you must align on with the client before printing it on the UI.

#AI Agent Production Checklist

Choosing the right tool is only half the battle. The other half—the part generic content farms never touch—is putting it in production without letting costs explode or losing control. For the Agent SDK and Claude Code, I look at six key points:

1. Least-privilege for tools. Declare allowed_tools (Python) / allowedTools (TS) to expose only what is necessary; block others using disallowed_tools. If an agent only needs to read files, do not enable Bash or Edit. This is a security boundary, not a configuration detail.
2. Cap token costs. An agent loop consumes far more tokens than a standard request. Set a limit on the number of turns, choose the right model tier for the right step (don't use the strongest model for simple steps), and leverage prompt caching for static system contexts.
3. Human-in-the-loop for irreversible actions. Use the PreToolUse hook to intercept and ask for confirmation before the agent runs delete commands, pushes code, or hits external APIs. Use the appropriate permission_mode to balance autonomy and safety.
4. Observability. Implement a PostToolUse hook to write audit logs every time a file is modified or a command is run. When something goes wrong, you should be able to trace exactly what the agent did, not guess.
5. Separated auth & billing. Run API keys server-side and track usage per-client from day one. This is the exact data you will need when pricing the next phase.
6. Handover scenario. Who operates it after you leave? Where are the JSONL session files stored? Who bears the cost if model pricing changes? Who manages the API keys? Answering these before shipping is what makes the agent truly "done."

#Conclusion

The Claude Agent SDK, Claude API, and Claude Code are not ranked from best to worst; they sit on a spectrum of delegation. The higher you go, the more responsibility (first the loop, then the infrastructure) you hand over to Anthropic, trading control for convenience. Choosing correctly means choosing the right rung for the right situation—and always asking "does this actually need an agent?" at the start, and "who will operate this post-handover?" at the end.

If you want to dive deeper into specific parts: the overall picture of building on Claude is covered in Claude Platform 101; Messages API and tool use are explained in Building with the Claude API; Claude Code is explored in Claude Code 101; and subagents (which the Agent SDK reuses under the hood) are discussed in Introduction to Subagents. The complete learning path is compiled at [/learn/claude?lang=en].

Nguyễn Phúc Nguyên Châu
Delivery Manager
14 years of delivery experience (Websites, Systems, AI Automation) for the Vietnam–Japan market