Anthropic ships two ways to build with Claude programmatically: the Claude API (the raw Messages endpoint) and the Claude Agent SDK (a framework built on top of it). The search traffic asking "Claude Agent SDK vs Claude API" is really asking one question: how much do I have to build myself?
What each one actually is
Claude API — direct HTTP access to Claude via the Messages endpoint. You send messages, get a response back. That's it. Every turn is stateless: if you want conversation history, tool use, memory, or a loop that keeps going until a task is done, you write that yourself.
Agent SDK — the same API underneath, wrapped in an agent loop Anthropic already built and maintains. It manages the conversation loop, ships working implementations of common tools (file read/write, bash, web search), handles context compaction when a session runs long, supports subagents and hooks, and gives you permission modes so you control what the agent can do without approval. It's what Claude Code itself is built on.
The real difference: who writes the loop
Every agentic system needs the same loop — call the model, check if it wants to use a tool, run the tool, feed the result back, repeat until done. With the raw API, you write that loop, you write the tool schemas, you write the tool execution code, and you decide what happens when the model runs long or gets stuck.
The Agent SDK gives you that loop already built. You register tools (or use its built-in ones), set a permission mode, and it manages turn-taking, context window pressure, and error recovery for you.
When to use the raw API
- A single request, single response. Summarize this document. Classify this ticket. Extract these fields. No back-and-forth, no tools, no loop — the API alone is the right amount of infrastructure.
- You need full control over the wire format. Building your own framework, streaming into a custom UI, or integrating with an existing agent framework that expects raw API calls.
- Cost-sensitive, high-volume, simple tasks. Fewer layers between you and the model means less to reason about when you're optimizing tokens and latency at scale. Pair this with prompt caching before you scale volume.
When to use the Agent SDK
- Anything that loops. If the task is "keep working until it's actually done" rather than "answer this one thing," you want the agent loop already solved for you.
- Anything that touches files, a shell, or multiple tools. The SDK ships working tool implementations instead of you writing your own file-read/file-write/bash-execution code and getting the edge cases wrong the first three times.
- Long-running sessions. Context compaction — trimming or summarizing history so a long session doesn't blow the context window — is handled for you. Hand-rolling this on the raw API is one of the more common places custom agent builds break in production.
- Multi-agent work. Subagents (spinning up a scoped, isolated Claude instance to do one piece of work and report back) are a first-class concept in the SDK. On the raw API, that's an architecture you design and maintain yourself.
What you give up with the Agent SDK
Less control over the exact loop mechanics, and another dependency to track versions of. If your use case is genuinely a single call-and-response, the SDK adds a layer you don't need. It's also opinionated about how tools and permissions are structured — if you have unusual requirements there, the raw API gives you more room to do it your own way.
The migration path
Most teams don't have to pick once and live with it. A common path: start on the raw API for a narrow feature (say, a summarization endpoint), and reach for the Agent SDK the moment that feature grows a second requirement — "now it should also check three other things before answering," "now it needs to loop until confidence is high enough," "now it needs to edit a file, not just respond." That inflection point — from one call to a loop that decides what to do next — is the actual signal to move up a layer, not company size or project age.
Where to go next
- Tool use patterns that don't burn tokens — the raw-API side of tool calling, useful whichever path you pick.
- Claude.ai vs Claude Code vs Claude API — which one when? — the broader decision tree this piece zooms into.
- Build your first MCP server — MCP is how both the API and the Agent SDK connect to external tools and data.