Claude Agent SDK
Use it when the agent touches files and commands
The loop is the least interesting thing it gives you. Control over which tools run without asking is the part that decides whether this ships.
The verdict
The Claude Agent SDK is the right choice when an agent has to read files, run commands and use tools across many turns, and the wrong one when a single well-shaped API call would answer the question.
Anthropic frames it plainly: it gives you the same tools, agent loop and context management that power Claude Code, programmable in Python and TypeScript. You are adopting a working agent runtime rather than assembling one.
Where it does not fit, the answer is the Client SDK. That is direct access to the API where you implement the tool loop yourself, which is the honest choice for a narrow, well-understood task.
In short
5 things that decide this
- 01The SDK is available as a library for Python and TypeScript only. Other languages run the CLI as a subprocess with the -p flag and JSON output.
- 02Permissions control which tools run automatically and which need approval, which is the feature that makes an agent with file and command access defensible.
- 03Hooks run custom code at points in the agent lifecycle, so logging and policy checks sit inside the loop rather than around it.
- 04Subagents spawn specialised agents for focused subtasks, and MCP connects external tools and data sources.
- 05Anthropic does not allow third-party developers to offer claude.ai login or rate limits for products built on the SDK unless previously approved. Use API key authentication.
For someone who has not built on it
An agent completes a task by planning its own steps and calling tools that read files, run commands or edit code. Writing that loop yourself is a week you will spend twice.
The SDK hands you the loop and the surrounding machinery: built-in tools for reading and writing files, running commands and searching the web, plus sessions that keep context across exchanges and can be resumed or forked later.
Which Anthropic tool for which job
Anthropic's own comparison is the clearest starting point, and it saves an argument. Building an agent without implementing the tool loop yourself points to the Agent SDK, a library that runs the loop in your own process. Calling the API directly and implementing the loop yourself points to the Client SDK.
There are two more doors. Interactive development and one-off terminal tasks belong to the CLI. Long-running or asynchronous agents where you would rather not manage your own sandbox point to Managed Agents, a hosted REST API and a separate product where Anthropic runs the agent and the sandbox.
Pick by where the loop runs and who owns the sandbox. That single question resolves most of these choices without a spike.
- PromptThe task, in plain language.
- PlanThe agent picks its next step.
- PermissionAuto-run, or ask a human.
- ToolRead, write, run, search.
- HookYour code, inside the loop.
- SessionContext to resume or fork.
The third station is the one that decides whether this is deployable. Everything else is convenience.
Where it stands
Good at
- Permissions are first-class, so you decide which tools run unattended and which stop for a person. That is the difference between a demo and something you let near a real system.
- Hooks put your logging, policy and safety checks inside the agent lifecycle instead of wrapped awkwardly around it.
- Sessions maintain context across exchanges and can be resumed or forked, which turns a long task into something recoverable.
- MCP support means an integration you build once is reachable by the agent rather than hard-wired into one prompt.
Weak at
- Library support is Python and TypeScript only. Any other language means driving the CLI as a subprocess, which is a workable but less pleasant integration.
- An agent with file and command access is a security design problem, and the SDK gives you the controls rather than the decisions. Getting the permission set wrong is on you.
- For a narrow task with one or two tools, the runtime is more machinery than the job needs and the Client SDK is the cleaner build.
- Branding rules constrain how you present it. Anthropic permits Claude Agent and Powered by Claude, and does not permit calling your product Claude Code or mimicking its visual elements.
- Authentication is prescribed. Offering claude.ai login or rate limits to your own users is not allowed without prior approval, so plan for API keys.
Claude and agent systems we run
Common questions
01Agent SDK or the Client SDK?
Use the Agent SDK when you want an agent loop you did not write, with tools, permissions and sessions included. Use the Client SDK for direct API access when you intend to implement the tool loop yourself. Anthropic draws the same line. The more your task looks like one structured call, the less the agent runtime earns.
02Can we build on it in a language other than Python or TypeScript?
Yes, through the CLI rather than a library. The documented route runs the CLI as a subprocess with the -p flag and JSON output. That gives you the same agent loop from any language. It is a heavier integration than importing a package, so factor it into the estimate.
03How do we stop an agent doing something destructive?
Permissions, and they are built for exactly this. You control which tools run automatically and which need approval. A read-only agent runs unattended, while anything that writes, sends or spends waits for a person. Pair that with hooks so every decision is recorded as it happens.
04Is this the same as Claude Code?
They share the engine, not the product. The SDK exposes the tools, agent loop and context management that power Claude Code as a library for your own application. Anthropic's branding rules also matter here: you may say Claude Agent or Powered by Claude, and you may not present your product as Claude Code.
