Claude Agent SDK vs Raw Anthropic API: When I Reach for Each

The Claude Agent SDK is Anthropic's library for building autonomous agents in Python and TypeScript. It packages the same agent loop, built-in tools, and context management that power Claude Code — so your agent can read files, run commands, search the web, and edit code without you writing a single line of tool-execution glue. Anthropic renamed it from the Claude Code SDK in September 2025, once it was clear the runtime worked for any agentic workflow, not just coding.

That rename matters more than it sounds. The thing that runs a coding agent — a loop that calls the model, executes a tool, feeds the result back, trims context when it fills up, and knows when to stop — is the exact thing you need for a research agent, a support agent, or the blog-publishing agent I run every morning. Anthropic productized that loop and stopped making everyone rebuild it.

This is the clearest way to feel the gap. With the client SDK, you own the while-loop:

# Raw Anthropic API — you write the loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)   # you build this
    response = client.messages.create(
        tool_result=result, **params)                # and this, every turn

With the Agent SDK, that entire loop collapses into a call that already knows how to use tools:

# Claude Agent SDK — the loop is built in
async for message in query(
    prompt="Find and fix the bug in auth.py",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash"])):
    print(message)   # Claude reads, finds the bug, edits — on its own

The first time I ported a home-grown agent onto the SDK, I deleted the tool dispatcher, the retry wrapper, the context-trimming helper, and the “did the model ask for a tool?” parser. Roughly 300 lines of my own plumbing became one allowed_toolslist. That plumbing wasn't clever code — it was code I had to keep alive, and now I don't.

“Batteries included” is a slogan until you name the batteries. Here are the ones I lean on every day:

• Built-in tools — Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch. My blog agent researches, writes the page, runs the build, and commits without me wiring a single tool handler.
• Subagents — I spin up isolated agents with their own context windows for parallel work, and only the summary comes back to the orchestrator. That's how I keep a long run from drowning its own context.
• Hooks and permissions — PreToolUse / PostToolUse hooks let me log, block, or transform actions, and permission modes gate the risky tools. My publish agent literally can't push until a build passes.
• Sessions and compaction — sessions persist as JSONL so I can resume or fork a run, and automatic compaction summarizes old messages before the context window fills, so a long agent doesn't just fall over.

It also speaks Model Context Protocol natively, so the same agent can reach a database or a browser through an MCP server. Just remember that every MCP server you bolt on spends tokens before the agent says a word — I wrote a whole post on what MCP servers actually cost you in tokens, and the lesson applies double inside a long-running SDK agent.

I'm not selling the SDK as the answer to everything. Plenty of my production calls are still the plain Anthropic API with a hand-built loop — or no loop at all. I reach for the raw API when:

• It's a single, well-defined call. Classify this ticket, extract these fields, rewrite this paragraph. There's no loop to inherit, so the SDK's machinery is dead weight.
• I need every token accounted for. Inside a tight n8n node or an edge function, I want to see exactly one request and one response, not an autonomous loop deciding how many calls to make.
• Dependencies have to stay minimal. A serverless function with a cold-start budget doesn't want a whole agent runtime riding along.
• The 'agent' is really a pipeline. If I already know the exact sequence of steps, deterministic control flow beats letting a model decide — that's a workflow, not an agent.

That last one is the mistake I see most. People reach for an agent framework when what they have is a five-step pipeline with known inputs. Wrapping deterministic work in an autonomous loop just adds cost and non-determinism. If you can draw the flow as a diagram, build the diagram — I learned that the hard way when my n8n agents started failing silentlybecause I'd handed the model decisions that belonged in code.

The rule in one sentence:if you'd end up rebuilding the agent loop, use the SDK; if you'd never write a loop at all, use the API. Everything in the table is just that rule applied.

The SDK is free; the tokens are not. An agent loop spends more than a single call by nature — it re-reads context, runs many tools, and iterates. Compaction and subagents help keep that in check, but they're not a budget. The first thing I add to any SDK agent that runs unattended is a hard token budget that aborts, model routing so the expensive model only touches the hard steps, and a kill-switch for repeated failures. That's not SDK-specific advice — it's the same discipline I put on every loop, and I laid it all out in running AI agents on autopilot without torching your budget.

If you want Anthropic's own framing, their engineering write-up on building agents with the Claude Agent SDK and the official Agent SDK overview are the two docs I actually keep open while building.

• The Agent SDK is Claude Code's agent loop, tools, and context management as a Python/TypeScript library — renamed from the Claude Code SDK in September 2025.
• Raw API: you write the tool loop. Agent SDK: Claude runs the loop and you hand it tools, permissions, and a goal.
• Use the SDK for genuinely agentic work — many tool calls, file access, long unattended runs, subagents, resumable sessions.
• Use the raw API for single tight calls, minimal dependencies, per-token control, and any task that's really a fixed pipeline.
• Decision rule: if you'd rebuild the agent loop, use the SDK; if you'd never write a loop, use the API.
• The SDK doesn't remove cost — put a hard budget, model routing, and a kill-switch on any loop before it runs alone.