- The rename from Claude Code SDK, in plain terms
- Four ways to build with Claude, and where the SDK fits
- What comes in the box
- How the agent loop runs, and how to cap it
- Who decides what the agent may do
- The cost number is an estimate, not your bill
- Sessions, subagents and memory between runs
- Hosting it yourself: what your team takes on
- Security, sign-in and branding rules
- Should your developer build on the Agent SDK?
- Frequently asked questions
The Claude Agent SDK is Anthropic's library for Python and TypeScript that gives a developer the same tools, agent loop and context management that power Claude Code, so that agent can run inside your own application. It used to be called the Claude Code SDK, and as of October 2026 the packages are claude-agent-sdk for Python and @anthropic-ai/claude-agent-sdk for TypeScript.
The rename from Claude Code SDK, in plain terms
The Claude Code SDK is now the Claude Agent SDK, and Anthropic says the new name reflects use for agents beyond coding tasks. The npm package moved from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk, the Python package from claude-code-sdk to claude-agent-sdk.
One change goes deeper than a name. Since version 0.1.0 the SDK no longer uses Claude Code's system prompt by default. Your developer either opts in to the claude_code preset or writes their own prompt, so ask which one your build uses. And the SDK hands your team the engine, not the running of it: hosting, storage, budgets and security are yours.
Four ways to build with Claude, and where the SDK fits
Anthropic's own comparison sets out four routes. What matters most to a buyer is who runs the agent loop.
| If you want to... | Use | Who runs it |
|---|---|---|
| Embed Claude Code's agent in your own app | Agent SDK, in Python or TypeScript | You, in a process you operate |
| Work interactively or run one-off tasks from a terminal | Claude Code CLI | A person at a terminal |
| Call the model directly and write the tool loop yourself | Client SDK on the Claude API | You write and run the loop |
| Have Anthropic host the agent and run the loop | Managed Agents | Anthropic |
If you're still working out what the API itself is, this guide to the Claude API covers the basics first.
What comes in the box
The overview lists built-in tools to edit files, run commands and search the web, plus hooks, subagents, MCP connections, permissions, sessions, skills, memory from the project's .claude folder, and plugins.
Your developer can add your own tools too. A custom tool has a name, a description Claude reads to decide when to call it, an input schema and a handler, and it's registered through the SDK's in-process MCP server. That's how an agent reaches your own functions, databases or APIs. MCP, the Model Context Protocol, is the open standard for connecting agents to outside tools and data.
By default the SDK also reads the same settings, CLAUDE.md files, skills, agents and commands as the Claude Code CLI. Passing an empty settingSources list switches that off, which Anthropic says matters for deployed apps and multi-tenant systems, so a developer's local customisations don't leak in.
How the agent loop runs, and how to cap it
Claude gets the prompt and decides whether to answer or call tools. The SDK runs the tools and feeds the results back, and that repeats until Claude replies with no tool calls. The final message carries the result text, token usage, cost and a session ID. A complex task can chain dozens of tool calls.
Without limits, the loop runs until Claude finishes, which can run long on open-ended prompts. There are two caps: a maximum number of turns, and the budget cap option, which stops the run at a spend threshold. Anthropic calls setting a budget a good default for production agents. I'd make it a condition of the build, not an extra.
Who decides what the agent may do
Permissions are checked in a fixed order:
- Hooks run first.
- Then deny rules.
- Then ask rules.
- Then the permission mode.
- Then allow rules.
- Finally, your own canUseTool callback.
A deny rule wins even in bypassPermissions mode, so it's the safest place for anything the agent must never touch. The allowedTools option pre-approves the tools you list, and in acceptEdits mode file edits are approved automatically.
The cost number is an estimate, not your bill
Here's the part most teams miss. The SDK's total cost field is worked out locally from a price table bundled into the SDK, and it can drift from what you're charged. Anthropic says to use it for development insight and rough budgeting, to use the Usage and Cost API or the Console Usage page for the real figure, and not to bill your own end users from it.
There's a second trap once subagents are involved: the plain usage field undercounts. Anthropic points to the modelUsage field for whole-tree token accounting, because it includes subagent requests. The total cost field includes them too.
Sessions, subagents and memory between runs
Sessions store the conversation, not the files. You can continue the latest session, resume one by its ID, or fork one to try a different direction. They sit on local disk by default, and file checkpointing is the separate tool for undoing file changes.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
Subagents are separate agent instances the main agent can spawn for focused subtasks. Anthropic lists four benefits: context isolation, parallel work, specialised instructions and tool restrictions. There's a built-in general-purpose one, or your developer can define their own. For how they behave inside Claude Code itself, this explainer on Claude Code subagents goes further.
Hosting it yourself: what your team takes on
Anthropic says this isn't like hosting a stateless API wrapper. Each query() call spawns a separate claude CLI process that owns a shell, a working directory and session files on disk, so every running agent is a long-lived process. Session transcripts, CLAUDE.md memory files and working-directory files don't survive a container restart unless you save them somewhere.
It names four hosting patterns: a throwaway container per task, long-running sessions, hybrid sessions that rehydrate from a session store, and several agents in one container. If you don't need the loop on your own infrastructure, Anthropic points to Managed Agents instead.
Getting started is light on paper. The quickstart needs Node.js 18.14 or later, or Python 3.10 or later, an Anthropic account and an API key from the Claude Console. Both SDKs bundle a native Claude Code binary, so most installs need nothing else. Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Microsoft Foundry are supported too.
Security, sign-in and branding rules
Agents can be steered by instructions hidden in files, web pages or user input, which is prompt injection, and they can simply make mistakes. Anthropic recommends defence in depth, from the built-in permission system and sandbox mode up to containers, gVisor or virtual machines, with least-privilege access and credentials injected through a proxy so the agent never sees them.
Unless Anthropic has approved it beforehand, you can't offer claude.ai login or claude.ai rate limits to your own users, and that includes agents built on the SDK: it has to be API key authentication. On branding, 'Claude Agent' or your agent's name followed by 'Powered by Claude' is fine, but 'Claude Code', 'Claude Code Agent' or look-alike visuals aren't.
A budget note: per Anthropic's 7 October 2026 release note, Max and Team plans include monthly API credits for running your own agents on the Claude Platform, claimed by linking a Claude Console organization in billing settings.
Should your developer build on the Agent SDK?
I'd ask a developer for the Agent SDK when you want Claude Code's agent inside your own product or internal tool and you're happy for your team to run the process. I wouldn't pick it if nobody wants to own hosting, because that's the job Managed Agents does for you. Before anyone starts, here's what I'd ask them:
- What's the budget cap and turn limit on every run?
- Where are sessions stored, and what happens to them when a container restarts?
- How is the agent isolated, and which files and network addresses can it reach?
- Who checks the real bill on the Console Usage page?
- Are your users signing in with API keys, not claude.ai logins?
If your team is about to build on the Agent SDK and wants the budget, hosting and safety questions settled first, that's the kind of thing I help with. I run AI training and workshops for teams, and help businesses with AI enablement, AI automation and GEO, which is about getting your business seen and cited in AI answers. Most of that work is with SaaS marketing teams, telecom companies and small businesses. Here's how we can work together.
Frequently asked questions
Is the Claude Agent SDK the same as the Claude Code SDK?
Yes. The Claude Code SDK was renamed the Claude Agent SDK. The npm package is now @anthropic-ai/claude-agent-sdk and the Python package is claude-agent-sdk.
Can I trust the cost figure the SDK reports?
Not for billing. It's an estimate from a price table bundled into the SDK. Anthropic says to check the Usage and Cost API or the Console Usage page instead.
Can users sign in to my agent with their Claude account?
Not unless Anthropic has approved it beforehand. Third-party developers can't offer claude.ai login or rate limits in their products, so agents built on the SDK use API key authentication.
What's the difference between the Agent SDK and Managed Agents?
With the Agent SDK, the agent runs in a process you host and operate. With Managed Agents, Anthropic hosts the agent and runs the loop for you.
