What is the Claude Agent SDK?
The Claude Agent SDK is Anthropic's library for building production AI agents in Python and TypeScript. It gives your application the same agent loop, built-in tools, and context management that power Claude Code — Anthropic's own coding agent — so Claude can autonomously read files, run shell commands, search the web, edit code, and call your own tools without you wiring up the orchestration by hand.
Anthropic renamed the package in late 2025. What used to be the Claude Code SDK became the Claude Agent SDK (the Python options class changed from ClaudeCodeOptions to ClaudeAgentOptions), signalling that this is no longer a coding-only tool. It is a general-purpose harness for any agent that needs to take real actions in the real world.
If you are still deciding whether an autonomous agent is the right pattern at all, start with our business guide to agentic AI. This article assumes you have already made that call and are choosing how to build.
How is the Claude Agent SDK different from the Anthropic API?
This is the distinction that trips up most teams. The plain Anthropic API (via the Client SDK) hands you a single model response. If the model wants to use a tool, you get a stop_reason of "tool_use", you execute the tool yourself, you feed the result back, and you loop again — you own every turn.
The Claude Agent SDK runs that loop for you. You call one function — query() in both languages — and Claude decides which tools to call, calls them, reads the results, and keeps going until the task is done. It also handles the unglamorous parts that break homegrown agents: context-window compaction when a session gets long, permission gating, and session persistence.
Rule of thumb: use the Client SDK when you want a single, tightly controlled model call. Use the Agent SDK when you want Claude to complete a multi-step task on its own.
What can you build with the Claude Agent SDK?
The SDK ships a set of primitives you compose into an agent:
- Built-in tools — Read, Write, Edit, Bash, Glob, Grep, WebSearch, and WebFetch work out of the box. Your agent can touch the filesystem and the terminal on day one.
- Custom tools — expose your own functions as in-process MCP tools. They run inside your Python or TypeScript process, with no subprocess or network hop.
- MCP servers — connect external systems (databases, browsers, SaaS APIs) through the Model Context Protocol without writing bespoke integrations.
- Subagents — spawn focused agents for sub-tasks. Each runs in its own context; only the final answer returns to the parent, which keeps the main context clean.
- Hooks — run your own code at lifecycle points (PreToolUse, PostToolUse, SessionStart, and more) to log, validate, or block actions deterministically.
- Permissions — allow-list safe tools, block dangerous ones, or require approval, so an agent cannot run rm -rf just because it felt like it.
- Sessions — persist, resume, and fork conversations so context survives across runs.
Practical builds include an internal research agent that reads your docs and the web, a CI agent that reviews and fixes pull requests, a data-ops agent that queries your warehouse and drafts reports, or a customer-facing assistant that acts on your own APIs.
What makes agents built on it production-ready?
Three capabilities matter most once you move past a demo:
- Structured outputs — the agent can return validated JSON matching a schema you define, so downstream code isn't parsing free text.
- Context compaction — long sessions are summarised automatically as they approach the context limit, instead of hard-failing mid-task.
- Fallback models and permissions — automatic model fallback improves reliability, while permission modes stop an autonomous agent from taking destructive actions.
When should you use the Claude Agent SDK?
Reach for it when all of these are true:
- The task needs multiple tool calls with reasoning between them, not a single completion.
- The agent should run inside your own infrastructure, with access to your files, code, and internal services.
- You want Anthropic's battle-tested harness for context management and permissions rather than maintaining your own.
- You are standardising on Claude models and are comfortable in Python or TypeScript.
Here is how it sits against the other ways to build with Claude:
| Option | Runs in | You handle | Best for |
|---|---|---|---|
| Anthropic Client SDK | Your process | The tool loop, yourself | Single, tightly controlled model calls |
| Claude Agent SDK | Your process / infra | Nothing — Claude runs the loop | Autonomous agents on your files and services |
| Claude Code CLI | Your terminal | Interactive prompts | Daily development and one-off tasks |
| Managed Agents | Anthropic's infra | No sandbox or session ops | Production agents without running your own infra |
A common path is to prototype locally with the Agent SDK, then move to Managed Agents once you need a hosted sandbox and long-running sessions.
Claude Agent SDK vs agent frameworks like LangGraph and CrewAI
The Agent SDK is not the only way to build agents, and it is not always the right one. Frameworks such as LangGraph, CrewAI, and AutoGen give you explicit control over multi-agent graphs, state, and model choice — including non-Claude models. The trade-off:
- Choose the Claude Agent SDK when you want the least code, are happy on Claude, and value a maintained tool harness.
- Choose a graph framework when you need deterministic control flow, mixed model providers, or complex branching. Our breakdown of LangGraph vs CrewAI vs AutoGen weighs those options in detail.
- Choose a visual automation platform when the workflow is mostly connecting SaaS tools with a little AI in the middle — our n8n agent tutorial walks through that route.
A five-step quick start
- Install the package — claude-agent-sdk for Python or @anthropic-ai/claude-agent-sdk for TypeScript. Both bundle the Claude Code binary, so there is nothing else to install.
- Set ANTHROPIC_API_KEY, or point the SDK at Amazon Bedrock, Google Vertex, or Microsoft Foundry.
- Call query() with your prompt and an options object listing the allowed tools — for example Read, Edit, and Bash for a bug-fixing agent.
- Iterate over the streamed messages to watch each step, or just read the final result.
- Add guardrails: tighten permissions, register a PostToolUse hook for auditing, and split heavy work into subagents.
You can have a working agent in a dozen lines. Making it safe, observable, and reliable in production is the real engineering — and where most teams underestimate the effort.
When is the Claude Agent SDK the wrong choice?
Skip it if your use case is a single prompt-and-response (use the plain API), if you must run open-source or multi-vendor models (use a framework), or if the "agent" is really a fixed pipeline with no branching (use a workflow tool). Autonomy has a cost: more tokens, more latency, and more surface area to secure. Only pay it when the task genuinely needs judgement between steps.
How ILMTEC helps
ILMTEC builds production agents on the Claude Agent SDK — and knows when not to. As an AI-native product-engineering firm and official n8n Expert Partner, we scope the right pattern (SDK, framework, or workflow), wire it into your data and systems, and ship it in fixed six-week cycles. If you are evaluating agentic AI and want a working prototype instead of a slide deck, see how we build AI applications and agents, and let's talk through your first build sprint.
