Claude Agent SDK

Also known as: Claude Code SDK

On this page 7

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.

ComponentRole in the loopTypical configuration
Query interfaceStarts a session and streams messagesOne-shot query() call or a persistent client
Built-in toolsRead, write and edit files, run shell commands, searchAllowed and disallowed tool lists
Permission systemApproves or blocks each tool callPermission mode plus a callback
HooksRun custom code before or after eventsPre-tool and post-tool handlers
MCP serversAdd external or custom toolsStdio, HTTP or in-process servers
SubagentsDelegate subtasks to isolated contextsNamed agent definitions with own prompts
Core components of the agent runtime

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.

ModeBehaviorSuitable for
DefaultAsks for approval on sensitive actionsInteractive use with a human present
Accept editsApplies file edits automaticallyTrusted refactoring in a sandbox
PlanAnalyzes and proposes, does not modifyReview before execution
Bypass permissionsRuns every allowed tool without askingIsolated containers only
Permission modes and their typical use

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.

FrameworkAbstraction levelModel supportMain strength
Claude Agent SDKComplete agent harnessClaude modelsBuilt-in tools and context management
OpenAI Agents SDKLightweight agent primitivesOpenAI and compatible modelsHandoffs and guardrails
LangGraphStateful graph orchestrationMany providersExplicit control flow and checkpoints
AutoGenMulti-agent conversationsMany providersAgent-to-agent dialogue patterns
CrewAIRole-based agent teamsMany providersFast setup of role workflows
Positioning against related agent frameworks

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.

SituationRecommended settingReason
Agent edits a code repositoryAccept edits mode inside a containerFast iteration with contained risk
Agent touches production dataDefault mode with a permission callbackHuman or policy check per action
Long research taskSubagents for each sourceProtects the main context window
Output feeds another programStructured output with a schemaReliable parsing downstream
Cost must stay boundedMaximum turns and budget limitsPrevents runaway loops
Configuration choices by situation

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.