Claude Agent SDK
Anthropic's Claude Agent SDK is a Python and TypeScript library for building agents that run on the same loop, tools and context handling as Claude Code.
Anthropic’s Claude Agent SDK is a toolkit for building AI agents. It works with two programming languages, Python and TypeScript. An agent, in Anthropic’s words, is a program that plans its own steps and uses tools to get a task done: reading files, running commands or editing code. The SDK gives you the loop, tools and memory handling that run inside Claude Code, Anthropic’s coding assistant. Anthropic renamed it from the Claude Code SDK because it can power many kinds of agents, not only coding ones.
Anthropic’s core idea is simple: give the agent a computer. Its built-in tools can open, create and change files, run terminal commands and look things up online. You can add more tools through the Model Context Protocol (MCP), a shared way to plug in outside tools and data.
Here is what happens when your app asks Claude to repair the broken tests in a file called auth.ts. Claude receives your request along with a system prompt (standing instructions), the list of tools it may use and the history so far. It replies with text, a request to use a tool, or both. Here it asks the Bash tool to run the tests, and some fail. Claude sees that, reads the two files, edits one and reruns the tests. Now they pass. Its last reply asks for no tool, so the loop stops. You get back a result with the answer, the cost and a session ID (a label for this conversation). It also lists the tokens used.
The key point is that Claude only asks to use a tool. The SDK decides whether the tool actually runs. It checks a row of gates, always in the same order. First come hooks, which are small functions of yours that run at set moments, such as just before a tool call. Next come deny rules, which always block. Then ask rules, which pass the call to your callback to confirm. Then the permission mode, an overall setting, and allow rules, which approve matching tools. Last is a callback: a function you write that makes the final yes or no. A deny rule wins even in the mode that otherwise approves everything. Hooks run in your own program, so they take up none of the agent’s memory.
That memory is the context window: all the information Claude can see during one session. It is not wiped clean after each round. The prompt, tool results and replies all pile up. When the window is nearly full, the SDK compacts it. It swaps older history for a summary. That can lose instructions you gave early on. Rules you always want followed belong in a CLAUDE.md file, which is sent again with every request. Subagents help too: helper agents with their own context windows that send back only what matters.
The SDK cannot make sure Claude’s plan is a good one. Without limits, the loop keeps going until Claude decides it is done. Anthropic suggests setting a spending budget for production agents, and you can also cap the number of turns. The agent runs on a computer you control. If you want Anthropic to host it instead, Managed Agents is a separate option.
Building an agent from scratch means writing a lot of plumbing before the useful part.
Follow one request, fix the failing tests, through the loop.
- 1 · promptClaude gets your request plus the standing instructions, the list of tools and the chat so far.
- 2 · decideClaude answers with text, one or more tool call requests, or both.
- 3 · checkBefore a tool runs, the SDK checks hooks, deny rules, ask rules, the permission mode, allow rules and then your callback.
- 4 · runThe SDK runs each approved tool and feeds the results back to Claude for its next decision.
- 5 · finishWhen Claude replies without any tool calls, the SDK hands back the answer along with tokens spent, cost and a session ID.
The model only asks. The SDK decides whether a requested tool actually runs.
| Who | What they ask | What it works with |
|---|---|---|
| Developer tools team | “Can an agent fix failing tests on its own?” | The repository files, a test command and file edits |
| Operations engineer | “Can we log every command the agent runs for an audit?” | A hook that fires before each tool call |
| Email app builder | “Can several searches of a mailbox run at once and report back only what matters?” | Search subagents with their own context windows |
- The SDK gives you the loop, tools and memory handling behind Claude Code as a library you call from code.
- Permission modes, allow and deny rules, hooks and a callback control which tool calls run.
- Sessions keep the conversation on disk so you can resume or branch a run later.
- Automatic compaction summarizes old history when the context window gets close to full.
- It does not make Claude's plan correct. Setting turn or spending limits is still your job.
- Sessions save the conversation, not the files. Undoing file changes needs a separate checkpoint feature.
- Compaction can drop early instructions, so lasting rules belong in a CLAUDE.md file.
- Products built on it may not offer claude.ai login unless Anthropic has approved it; they use API keys instead.
Sources used
This explainer is written in original language. The links below support its factual claims.
- docsAgent SDK overview, Anthropic · read 28 Sept 2026
- docsHow the agent loop works, Anthropic · read 28 Sept 2026
- docsConfigure permissions, Anthropic · read 28 Sept 2026
- docsIntercept and control agent behavior with hooks, Anthropic · read 28 Sept 2026
- docsWork with sessions, Anthropic · read 28 Sept 2026
- officialBuilding agents with the Claude Agent SDK, Anthropic · read 28 Sept 2026
- repoclaude-agent-sdk-python, Anthropic on GitHub · read 28 Sept 2026