Agent SDK, Managed Agents, or the raw API

Before choosing a tool, decide whether you are building an agent at all — most tasks are a single well-shaped API call, not a loop. This page is for after that question resolves to "yes, a loop", and it separates the ways to get one by a single axis: who runs the agent loop, and who runs the sandbox.

Who does the work

The platform documentation lays them out directly.

The raw API (Client SDK). You are "Calling the API directly and implementing the tool loop yourself". Maximum control, maximum surface area: retries, tool dispatch, context management and error handling, all yours. Correct when your loop is genuinely unusual; expensive when it is not, because you are rebuilding what the SDK already ships.

The Agent SDK. A library that "runs the agent loop in your own process, in Python or TypeScript", and it is not a thin wrapper — it "gives you the same tools, agent loop, and context management that power Claude Code". You bring the environment and the credentials; it brings the loop, tools, hooks, subagents and permissions. The default answer for most agents.

Managed Agents. A "Hosted REST API, a separate product from the Agent SDK", where "Anthropic runs the agent and the sandbox". You give up control of the execution environment and get out of the business of running one: the right trade for long-running or asynchronous agents you do not want to babysit.

The Claude Code CLI. The terminal interface for interactive use, and the escape hatch for other languages, since the SDK is "available as a library for Python and TypeScript only": drive the same loop from anywhere by running the CLI as a subprocess.

The axis that decides it

These questions place almost any project:

Do you need to own the execution environment? If the agent must run inside your network, touch your filesystem, or use credentials that cannot leave your infrastructure, the loop runs in your process: Agent SDK, or the raw API if the SDK's loop does not fit. If you would rather not operate a sandbox at all, that is the Managed Agents pitch in one sentence.

Is your loop ordinary or exotic? The SDK's loop is the Claude Code loop: tool use, permissions, context management, subagents. If that shape fits, and it fits most agents, reimplementing it on the raw API is cost without return. Drop to the raw API only when you can name the specific thing the SDK's loop will not let you do.

The trap is picking by familiarity: reaching for the raw API because you have called it before, and inheriting the retry logic, the streaming assembly and the tool-dispatch bugs the SDK would have handled. Reach down a layer only for a reason you can state.

What goes wrong

Rebuilding the SDK on the raw API. Hand-rolling the agent loop when the SDK's loop fit — every bug in retries, context and tool dispatch is now yours to find in production.

Managed Agents for work that needs local reach. The hosted sandbox cannot see your filesystem or your private network. If the task's whole point is your environment, the hosted product is the wrong shape.

Self-hosting a sandbox you did not want. The mirror mistake: running your own long-lived agent infrastructure (session storage, isolation, uptime) when Managed Agents existed to take exactly that off you.

Choosing the loop before choosing to have one. The most expensive agent is the one that should have been a single API call. Settle that first.

Language lock-in surprise. Building around the SDK in a Ruby or Go shop without noticing it is Python/TypeScript only, then discovering the subprocess bridge late.

How to check it worked

State your choice as one sentence with the axis in it: "the loop runs in our process because X, and it is the SDK's loop because Y." If X is "we've always called the API" or Y is "it felt more flexible", you chose by habit, not by the axis — go back to the two questions. The right choice reads like a constraint, not a preference.