Claude Agent SDK: What It Is and When to Use It
What the Claude Agent SDK provides, where it fits and how to choose between the Agent SDK, Claude Code and a direct API client.
Co-founder of Ampliflow. Builds AI automation, websites, SEO/AEO, and growth systems for UK SMEs.
- 01What the Claude Agent SDK provides
- 02A minimal TypeScript example
- 03Agent SDK vs Claude Code, client SDK and Managed Agents
- 04When the Agent SDK is a good fit
- 05Permissions are product design
The Claude Agent SDK gives developers the agent loop, tools and context management behind Claude Code as a Python or TypeScript library. It is useful when Claude needs to act inside your application or workflow rather than wait in an interactive terminal.
That does not make it the default choice. If a person is doing the work in a repository, Claude Code is usually simpler. If your application only needs a model response, the standard client SDK may be enough. The Agent SDK earns its place when the product needs a governed agent that can inspect context, choose tools and continue across several steps.
Anthropic's official Agent SDK overview is the source of truth for current packages and capabilities.
What the Claude Agent SDK provides
The SDK packages together several parts developers would otherwise have to build:
- an agent loop that continues after tool calls;
- built-in file, shell and web tools;
- permission controls for allowed and blocked actions;
- hooks around tool use and session events;
- session continuation and context management;
- subagents for bounded specialist work;
- MCP support for external tools.
The attraction is not that an agent can run a command. Any application can run a command. The value is that the loop, messages, tool results and continuation behaviour already share a coherent model.
A minimal TypeScript example
typescriptimport { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Review the changed files and report defects. Do not edit anything.",
options: {
allowedTools: ["Read", "Glob", "Grep"],
},
})) {
console.log(message);
}The important part is not the small amount of code. It is the explicit tool boundary. An agent asked to review files does not need Write or Bash by default.
Production code also needs timeouts, cost controls, structured outputs, logging and a clear failure path. The SDK removes boilerplate around the loop; it does not remove operational responsibility.
Agent SDK vs Claude Code, client SDK and Managed Agents
- 01Claude Code — interactive repository work
- 02Agent SDK — multi-step agents in an application
- 03Client SDK — direct model access
- 04Managed Agents — hosted asynchronous agents
| Need | Best starting point | Why |
|---|---|---|
| A person works interactively in a terminal | Claude Code | The interface, approvals and repository workflow already exist |
| An application runs a multi-step agent | Claude Agent SDK | The agent loop and tools are built in |
| An application sends prompts and handles its own logic | Anthropic client SDK | Direct model access without an extra agent layer |
| A hosted service runs long-lived or asynchronous agents | Managed Agents | Anthropic hosts the agent, sandbox and session infrastructure |
There is also a simpler option outside Anthropic's four-way comparison. If the task is “copy these five validated fields from system A to system B”, ordinary deterministic code is cheaper to test and easier to audit. Use an agent where interpretation or changing context is part of the job.
When the Agent SDK is a good fit
Repository review
An internal service can inspect a pull request, read the relevant standards and return structured findings. Keep merge, deployment and external comments behind explicit permissions.
Research with a fixed output contract
An agent can search, read and compare sources, then return a schema containing claims and citations. A human should still review high-stakes conclusions and source quality.
Support triage
The agent can classify a message, retrieve approved knowledge and draft a reply. Sending, refunds, account changes and sensitive cases should have separate gates.
Operations investigation
An agent can assemble a diagnostic pack from logs, dashboards and documentation. Start read-only. Remediation is a different permission tier.
When not to use it
Do not choose the Agent SDK because “agentic” sounds more capable. Avoid it when:
- the workflow is a short, deterministic function;
- the required data should not be available to a model;
- nobody owns evaluation and incident response;
- an ordinary queue and API integration already solve the problem;
- the only success criterion is that the demo looked convincing.
The lazy architecture is often the reliable one: normal code for fixed rules, an agent only for the judgement-shaped part.
Permissions are product design
Tool permissions are not a final security wrapper. They define what the product is.
A useful progression is:
- read a fixed test fixture;
- read a limited non-production system;
- draft a proposed action;
- require approval before the action;
- allow a narrow reversible action;
- add broader access only from observed need.
Keep identities separate between development, testing and production. Never pass a broad personal credential to an unattended agent. Log the request, tool, target and outcome without logging secrets.
How to evaluate an agent before production
Create a small set of representative tasks, including awkward and unsafe cases. Measure outcomes a reviewer can see:
- Did it produce the required result?
- Did it stay inside the tool boundary?
- Did it cite or preserve evidence?
- Did it stop when information was missing?
- Did it avoid changing external state without approval?
- What did the successful run cost and how long did it take?
Run the same set after prompt, model, tool or SDK changes. “It worked yesterday” is not a release test.
Operating costs and reliability
The package is only one cost. Model usage grows with input context, tool output, retries and the number of turns. Infrastructure, monitoring and human review also count.
Control the shape of the work before optimising model prices:
- return only relevant fields from tools;
- cap large results;
- use structured output where the next system expects structure;
- stop repeated failure loops;
- keep a deterministic path for routine operations;
- set a hard spend ceiling.
Check Anthropic's current pricing and package documentation when planning a release. Product terms change more quickly than architecture principles.
Frequently asked questions
Is the Claude Agent SDK the same as Claude Code?
No. Claude Code is the interactive product. The Agent SDK exposes agent capabilities for developers to use in their own software.
Which languages are supported?
Anthropic documents Python and TypeScript SDKs. Use the official overview for current installation commands and version requirements.
Do I need MCP as well?
Only if the agent needs tools exposed through MCP. Built-in tools or a normal application function may cover the workflow with less access.
Can the SDK run without human approval?
Technically, some workflows can. Whether they should depends on the consequence. External messages, publication, spending, deletion and production changes deserve explicit controls.
Related reading
If you have a real workflow but the architecture is still fuzzy, Get unstuck.