The Claude Agent SDK is Anthropic’s software development kit for building autonomous agents on top of Claude models, packaging the same agent loop, tools and context management that power the Claude Code command-line assistant. Among AI frameworks & tools, it sits at the agent-runtime layer: instead of sending single requests to a model, a developer starts an agent that plans, calls tools, reads results and iterates until a task is finished.
The library was first released as the Claude Code SDK and later renamed to reflect that it serves general agents, not only coding assistants. It is distributed as a Python package and a TypeScript package, and it runs locally or on a server where the agent can access a file system, a shell and external services.
How the Claude Agent SDK runs an agent loop
The Claude Agent SDK runs a gather context, act, verify loop: the model receives a prompt and a list of available tools, decides which tool to call, the SDK executes that call, and the result is returned to the model as new context. The loop repeats until the model produces a final answer or a turn or budget limit stops it.
Unlike a plain model API client, the SDK executes tools itself rather than leaving that work to the developer. It manages the conversation history, applies automatic context compaction when the context window fills up, and streams typed messages (assistant text, tool calls, tool results and a final result with cost and usage) back to the calling program.
The main components of the runtime are summarized below.
| Component | Role in the loop | Typical configuration |
|---|---|---|
| Query interface | Starts a session and streams messages | One-shot query() call or a persistent client |
| Built-in tools | Read, write and edit files, run shell commands, search | Allowed and disallowed tool lists |
| Permission system | Approves or blocks each tool call | Permission mode plus a callback |
| Hooks | Run custom code before or after events | Pre-tool and post-tool handlers |
| MCP servers | Add external or custom tools | Stdio, HTTP or in-process servers |
| Subagents | Delegate subtasks to isolated contexts | Named agent definitions with own prompts |
Tools, permissions and hooks
Tools define what an agent built with the Claude Agent SDK can actually do, and permissions decide which of those actions run without human review. The built-in set includes file tools (Read, Write, Edit, Glob, Grep), a Bash tool for shell commands and web tools for search and fetching pages. Developers add domain tools through the Model Context Protocol (MCP), either by connecting existing MCP servers or by defining in-process tools as ordinary functions.
The permission layer is the main safety control. A permission mode sets the default behavior, and a permission callback can inspect each proposed call, approve it, deny it or rewrite its input. The following table compares the standard modes.
| Mode | Behavior | Suitable for |
|---|---|---|
| Default | Asks for approval on sensitive actions | Interactive use with a human present |
| Accept edits | Applies file edits automatically | Trusted refactoring in a sandbox |
| Plan | Analyzes and proposes, does not modify | Review before execution |
| Bypass permissions | Runs every allowed tool without asking | Isolated containers only |
Hooks extend control further. A pre-tool hook can block a shell command that matches a dangerous pattern, and a post-tool hook can log every file change to an audit trail. Because hooks are deterministic code rather than model instructions, they are the reliable place for rules that must never be broken.
How it compares with other agent frameworks
The Claude Agent SDK differs from most agent frameworks because it ships a ready-made, opinionated agent harness rather than a toolkit for assembling one. Frameworks such as LangGraph or AutoGen give developers graph or conversation primitives and leave tool execution, file access and context handling to them, while the SDK provides these out of the box.
| Framework | Abstraction level | Model support | Main strength |
|---|---|---|---|
| Claude Agent SDK | Complete agent harness | Claude models | Built-in tools and context management |
| OpenAI Agents SDK | Lightweight agent primitives | OpenAI and compatible models | Handoffs and guardrails |
| LangGraph | Stateful graph orchestration | Many providers | Explicit control flow and checkpoints |
| AutoGen | Multi-agent conversations | Many providers | Agent-to-agent dialogue patterns |
| CrewAI | Role-based agent teams | Many providers | Fast setup of role workflows |
The trade-off is capability versus portability. The SDK gives strong results with little code for tasks such as code changes, research and document processing, but it is tied to Claude models and to the design choices of its harness. Teams that need provider independence or a precisely modeled workflow often choose a graph framework instead.
Configuring an agent for production
A production agent built with the Claude Agent SDK is defined mostly through configuration options: the system prompt, the allowed tools, the working directory, the permission mode, the maximum number of turns and the MCP servers to load. The system prompt can be fully custom or extend the Claude Code preset, which already contains detailed tool-use guidance.
Other features matter once agents run unattended. Session resumption lets a program continue an earlier conversation by its session identifier, structured output forces the final answer into a JSON schema, and subagents keep long investigations in separate context windows so the main agent receives only a summary. The decision table below links common situations to recommended settings.
| Situation | Recommended setting | Reason |
|---|---|---|
| Agent edits a code repository | Accept edits mode inside a container | Fast iteration with contained risk |
| Agent touches production data | Default mode with a permission callback | Human or policy check per action |
| Long research task | Subagents for each source | Protects the main context window |
| Output feeds another program | Structured output with a schema | Reliable parsing downstream |
| Cost must stay bounded | Maximum turns and budget limits | Prevents runaway loops |
Limitations and common mistakes
The most serious risk with the Claude Agent SDK is granting broad tool access without isolation. An agent with an unrestricted shell can delete files, leak secrets or follow prompt injection hidden in a web page or document it reads. Experienced teams treat every agent as untrusted code and run it in a container or virtual machine with minimal credentials.
- Using bypass mode on a developer laptop exposes personal files and credentials to the agent.
- Relying on prompt instructions for safety fails under injection; hooks and permission callbacks are enforceable.
- Ignoring cost and turn limits lets a confused agent loop for many expensive turns.
- Loading too many MCP tools inflates the context and makes tool selection less accurate.
- Skipping evaluation hides regressions when prompts, tools or model versions change.
Agents are also non-deterministic: the same task can take different tool paths on different runs. Reliable deployments therefore combine logging of every tool call, test suites of representative tasks and clear success criteria that the agent can verify by itself, for example by running tests after editing code.
In plain words
The Claude Agent SDK is a toolkit that lets programmers build an AI helper that does work, not only talks. A normal chatbot answers a question and stops. An agent built with this kit can open files, run programs, search the web and check its own results, step by step, until the job is done.
Think of it as hiring a capable assistant and giving it a desk, a computer and a set of keys. The SDK supplies the desk and the computer. The developer decides which keys the assistant receives and which actions need approval first. Good results depend on careful limits, just as with a new employee.
A real-world example
A mid-sized software company receives about 40 bug reports a week. Its platform team builds a triage agent with the Claude Agent SDK that runs in a disposable container for each report. The agent reads the report, searches the repository with the file tools, reproduces the problem by running the test suite through the shell tool and drafts a fix on a separate branch.
The team allows file edits automatically but uses a pre-tool hook that blocks network access and any command touching deployment scripts. A maximum of 30 turns and a structured output schema make each run return a summary, the suspected cause and a test result. Engineers review the proposed branches instead of starting from scratch, and first-response time on bug reports falls from days to hours while every merge still passes human review.