Claude Agent SDK Explained: Building Production Agents on Claude's Harness
Most agent projects stall at the same point: the model can describe what to do, but someone has to write the loop that runs tools, feeds results back and stops at the right moment. The Claude Agent SDK ships that loop ready-made. It is the harness behind Claude Code, exposed as a Python and TypeScript library. This guide covers how it works, where it fits, what it takes to run in production and where it falls short. Facts are checked as of October 2026.
What is the Claude Agent SDK and what is it for?
The Claude Agent SDK is Anthropic's library for building agents that plan their own steps and act through tools. According to the official overview, it gives you the same tools, agent loop and context management that power Claude Code, programmable from Python and TypeScript.
That is what sets it apart. Most agent frameworks hand you a model client and a set of abstractions, and you write the tools. The Agent SDK hands you a working runtime: file editing, shell access, web search, permission checks and session storage are already there. Under the hood, the hosting documentation explains, each query() call spawns a Claude Code subprocess and talks to it over stdio.
Anthropic positions the SDK against three neighbours:
- Claude Code CLI for interactive work in a terminal.
- Client SDK for calling the Claude API directly, where you write the tool loop yourself or use the beta tool runner.
- Managed Agents, where Anthropic hosts the loop and tools run in a managed or self-hosted sandbox.
Choose the Agent SDK when the agent lives inside your own application and you operate the process. Realistic workloads include triaging inspection reports in a shared folder, matching support tickets against log files, drafting quotes from templates and master data, and maintenance work in CI pipelines.
The product used to be called the Claude Code SDK. The migration guide says the rename reflects its use for agents well beyond coding.
How does the Claude Agent SDK work?
The SDK runs a loop. Claude receives your prompt, the system prompt, tool definitions and history, then either answers or requests tool calls. The SDK executes those calls, returns the results, and the cycle repeats until Claude replies without calling a tool. Your code consumes a stream of typed messages throughout.
The agent loop documentation defines five core message types: SystemMessage for lifecycle events such as session start or compaction, AssistantMessage for text or tool requests, UserMessage for tool results, StreamEvent when partial streaming is on, and ResultMessage carrying the final text, token usage, cost and session ID.
Built-in tools
You get these without writing any tool code:
| Category | Tools |
|---|---|
| Files | Read, Edit, Write |
| Search | Glob, Grep |
| Execution | Bash |
| Web | WebSearch, WebFetch |
| Orchestration | Agent, Skill, AskUserQuestion, TaskCreate, TaskUpdate |
ToolSearch loads tool schemas on demand instead of up front. For your own tools, Python uses the @tool decorator and create_sdk_mcp_server; the custom tools page notes that this MCP server runs inside your application process. External systems connect through the Model Context Protocol.
Permissions and hooks
Every tool call passes a fixed sequence of checks, set out in the permissions guide: hooks first, then deny rules, ask rules, the permission mode, allow rules, and finally your canUseTool callback. A deny rule still blocks in bypassPermissions mode. Hooks such as PreToolUse run in your process and cost no context.
The modes are default (unresolved calls go to your callback, or are denied without one), acceptEdits (file edits inside the working directory are approved), plan (explore and propose, no edits), dontAsk (anything not pre-approved is denied), auto (a classifier model reviews actions) and bypassPermissions (for isolated environments only).
Effort and parallel execution
You also control how hard Claude thinks. The effort option takes low, medium, high, xhigh or max, and the documentation notes that lower levels use fewer tokens per turn. An agent that only lists files is fine on low; debugging across several modules calls for high. Subagents can override the session level.
When Claude requests several tools in one turn, the SDK runs read-only tools such as Read, Glob and Grep concurrently and state-changing ones such as Edit, Write and Bash one after another. Custom tools default to sequential execution unless you set the readOnlyHint annotation. That annotation is metadata, not enforcement: if the handler writes anyway, the SDK will not stop it.
Context, compaction and sessions
When the context window nears its limit, the SDK summarises older history and emits a compact_boundary message. Early instructions can be lost in that summary, so Anthropic recommends putting standing rules in a CLAUDE.md file, which is re-injected on every request. Sessions can be resumed or forked by ID.
Where does the SDK fit in a company?
The SDK fits work where an agent must plan several steps and touch real files or systems. It is overkill for single-shot question answering, where one API call does the job. Four patterns come up repeatedly.
Document agents. An agent reads a folder of delivery notes, test reports or spreadsheet exports, cross-checks them and writes a summary. File tools are built in, and Read(path) and Edit(path) rules restrict which directories it may touch.
Service and knowledge agents. An agent searches manuals, ticket history and logs for the cause of a fault, calling the ticketing system through a custom MCP tool. The business side of such agents is outlined on the page about AI agents for technical service.
Engineering and CI agents. Running tests, reading failures and proposing fixes is where Claude Code started; the SDK moves it into your own pipelines.
Orchestrated multi-step agents. A lead agent delegates subtasks to subagents. Per the documentation, a subagent returns only its final answer, which keeps the lead agent's context small.
How the SDK compares with LangGraph, CrewAI or the OpenAI Agents SDK is covered in our honest framework comparison. In short, many alternatives are model-agnostic and lean towards explicit workflow graphs; the Claude Agent SDK is tied to Claude but brings a complete tool and permission layer. For plans and data protection questions around Claude itself, see Claude for business.
What do you need before you start?
You need Python 3.10 or Node.js 18, access to the Claude API or a supported cloud provider, and an execution environment where the agent can safely use files and commands. Just as important is a written decision on which systems the agent may touch and who owns its output.
Technical requirements
- Runtime: Python 3.10+ or Node.js 18+, per the quickstart. On 24 October 2026, PyPI listed
claude-agent-sdkversion 0.2.174. - Authentication:
ANTHROPIC_API_KEY, or a cloud route:CLAUDE_CODE_USE_BEDROCK=1for Amazon Bedrock,CLAUDE_CODE_USE_VERTEX=1for Google Cloud,CLAUDE_CODE_USE_FOUNDRY=1for Microsoft Foundry, or Claude Platform on AWS. - Resources: the hosting guide suggests 1 GiB RAM, 5 GiB disk and 1 CPU per agent as a starting point; memory grows with session length and tool activity.
- Network: outbound HTTPS to
api.anthropic.comor your provider's regional endpoint.
On licensing, note one constraint: without Anthropic's approval, products may not let users sign in with claude.ai or draw on subscription limits. Production agents need API billing.
Data and organisation
An agent can only work with what it can reach. Settle in advance where input data lives (file share, SharePoint, ERP export), which actions the agent may take on its own and which it may only propose, and who reviews results before they reach customers. If personal data is involved, data processing agreements and data residency belong on the list. Running through a cloud provider's EU region can help you operate in line with the GDPR, but this is orientation, not legal advice.
How do you roll it out step by step?
Start with one narrow process, a read-only agent and hard caps on turns and spend. Widen write access only after you have read the transcripts of several runs. Five steps work well.
- Pick a process. A recurring task with a clear output, such as "summarise this week's inspection reports and flag deviations".
- Prototype read-only. Use
allowed_tools=["Read", "Glob", "Grep"]withpermission_mode="dontAsk", so the agent runs unattended but cannot change anything. - Add custom tools. Wrap ERP, ticketing or database access in
@toolfunctions rather than handing the agent a shell. - Set limits.
max_turnsandmax_budget_usdcap round trips and estimated spend. Without them, the loop runs until Claude decides it is done, which can take a long time on open-ended prompts. - Plan operations. Choose ephemeral containers per task or a long-running service, persist transcripts with a
SessionStore, enable OpenTelemetry export, and route outbound traffic through a proxy with a domain allowlist.
Which deployment pattern fits?
The hosting guide describes four patterns, distinguished by how long a container lives:
- Ephemeral sessions: one container per task, destroyed when it finishes. Suits invoice extraction, document translation or a single bug investigation.
- Long-running sessions: persistent containers holding several SDK processes, for example an agent that triages incoming email. Size them for peak concurrent sessions.
- Hybrid sessions: short-lived containers that load the transcript from a
SessionStoreon start and write updates back. Without a store, the transcript is lost on shutdown. - Multi-agent container: several closely cooperating agents in one container, each with its own working directory.
For monitoring, the SDK picks up OpenTelemetry settings from the environment. Prompt text and tool inputs are excluded from exports by default, which simplifies conversations with your data protection officer.
A minimal read-only agent looks like this (Python, claude-agent-sdk 0.2.174, October 2026):
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
options = ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep"], # read-only
permission_mode="dontAsk", # deny everything else
max_turns=20, # cap round trips
cwd="./inspection-reports", # working directory
)
async for message in query(
prompt="Summarise all deviations in this week's inspection reports.",
options=options,
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
asyncio.run(main())
A hands-on quickstart with tests and custom tools will follow as a separate article in this section.
What are the limits and risks?
The SDK takes the loop off your hands, not the responsibility for operations, security and cost. The main risks are overly broad permissions, unbounded runs, unplanned memory growth and lock-in to Claude as the model.
- Model lock-in. The SDK runs Claude models. If you need to mix providers, a model-agnostic framework is the better base.
- Not a stateless service. Each session is its own subprocess with a shell, working directory and transcript files. A container restart wipes that state unless you persist it.
- Permission pitfalls.
allowed_toolsdoes not restrictbypassPermissions; the documentation warns that every tool is then approved. Auto-approved calls never reachcanUseTool, so mandatory checks belong in aPreToolUsehook. - Filesystem settings. If you omit
setting_sources, the SDK loads user, project and local settings, including CLAUDE.md, just like the CLI. Multi-tenant systems must switch this off or context can leak between tenants. - No session timeout. The hosting guide lists the absence of a top-level session timeout as a known limitation;
max_turnsis the bound. - Cost. According to Anthropic, token spend typically exceeds container cost by an order of magnitude or more. Budget caps and per-session cost tracking are not optional.
- Compaction. Early instructions may not survive summarisation. Keep fixed rules in configuration or CLAUDE.md rather than only in the first prompt.
In our own operations, most failures traced back not to the model but to generous permissions and missing caps on turns and spend.
How do you get started?
Install the SDK, set an API key and point a read-only agent at a test folder. Then decide from real transcripts whether the SDK fits your process, or whether a single API call, another framework or a hosted agent would serve you better.
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
export ANTHROPIC_API_KEY=your-api-key
After the first run, check three things. Which tools did the agent call? How many turns and how much cost does the ResultMessage report? Would you have broken the task down the same way? If the answers look right, move on to custom tools and a hardened deployment.
For an overview of how such agents are built for quoting, service, knowledge and sales work, see the page on AI agents for mid-sized companies.
Frequently asked questions
What happened to the Claude Code SDK?
It was renamed. The packages are now claude-agent-sdk on PyPI and @anthropic-ai/claude-agent-sdk on npm, and the Python options class changed from ClaudeCodeOptions to ClaudeAgentOptions.
Can my product use people's Claude Pro or Max subscriptions?
Not without approval. Anthropic states that third-party developers may not offer claude.ai login or rate limits in their products, including agents built on the SDK, so production agents authenticate with an API key or a cloud provider.
Which cloud providers can serve the models?
Besides the Claude API, the quickstart lists Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Microsoft Foundry, each enabled through an environment variable plus that provider's credentials.
Is the Agent SDK a good fit for a simple chatbot?
Usually not. If one model call answers the question, the plain Client SDK is lighter; the Agent SDK pays off when the model has to plan several steps and use tools.
How is usage of the SDK licensed?
Use is governed by Anthropic's Commercial Terms of Service, including when you build products for your own customers. Individual components may carry their own licence, stated in their LICENSE file.
Sources
- Anthropic: Agent SDK overview code.claude.com
- Anthropic: How the agent loop works code.claude.com
- Anthropic: Configure permissions (Agent SDK) code.claude.com
- Anthropic: Agent SDK Quickstart code.claude.com
- Anthropic: Hosting the Agent SDK code.claude.com
- Anthropic: Give Claude custom tools code.claude.com
- Anthropic: Migrate to Claude Agent SDK code.claude.com
- PyPI: claude-agent-sdk pypi.org