Claude Agent SDK: What It Is, How It Works, and What It Does Not Handle

TL;DR

The Claude Agent SDK is Anthropic's framework for building custom agents on the same harness that powers Claude Code: an agentic loop with tool use, file access, subagents, hooks and skills, packaged as a library for TypeScript and Python. It is the fastest path from "we want an agent" to a working one, because the loop, permissioning and context management are already built. What it deliberately does not provide is durable organizational knowledge: sessions end, and what the agent learned ends with them unless you persist it somewhere. This guide covers what the SDK gives you, the decisions it makes for you, and where its boundaries sit.

What is the Claude Agent SDK, mechanically?

The SDK exposes the agent harness Anthropic built for Claude Code as a programmable library. Instead of assembling your own loop around the Messages API, you get the production loop Anthropic runs, with the pieces that make agents workable:

1. The agentic loop. The model plans, calls tools, reads results and continues until the task resolves, with context compaction handled for you as conversations grow.

2. Tools and permissions. File operations, shell execution and web access ship as built-in tools, each gated by a permission system, so an agent can be granted read access without write access.

3. Subagents. Work can be delegated to separate agent instances with their own context windows, which keeps a long search from flooding the main conversation.

4. Hooks. Deterministic code that runs at defined points in the loop, such as before a tool call, which is how teams enforce rules the model should never be able to skip.

5. MCP support. Any Model Context Protocol server plugs in as a tool source, so the agent can reach the systems your company already runs.

6. Skills. Packaged instruction sets that load on demand when the task matches, so procedural knowledge does not sit in the prompt permanently.

The design premise, stated in Anthropic's own engineering writing, is that agents need the same things a developer's workstation provides: a computer, files, tools and a way to check their work.

What decisions does the SDK make for you?

Adopting the SDK means accepting a set of defaults, and most of them are the right ones:

1. Context is managed, not unlimited. The harness compacts and summarises as sessions grow rather than letting the window overflow. You trade some control for not having to build compaction yourself.

2. Safety is permission-first. Tools ask before acting by default, and autonomy is something you grant deliberately, per tool, rather than something you claw back after an incident.

3. State lives in files. The SDK's native persistence surface is the filesystem: instruction files, skill folders, scratch files. This is simple and inspectable, and it is also the boundary that matters most for teams, covered below.

4. The model does the orchestration. Control flow emerges from the model's decisions rather than from a graph you define, which is faster to build and harder to make deterministic. Teams that need fixed pipelines add hooks or wrap the SDK in their own scheduler.

What does the SDK not handle?

Three boundaries show up in production, and none of them are flaws so much as scope decisions:

1. Memory beyond the session. When a session ends, the agent's accumulated understanding ends with it. CLAUDE.md files persist stable instructions, but conclusions the agent reached, decisions it observed and facts it derived are gone unless you write them somewhere. The SDK gives you the filesystem as the persistence primitive and leaves the schema to you.

2. Shared state across agents. Two agents built on the SDK do not share what they learn, even inside one company. Each session assembles context from its own inputs. Anything organization-wide, such as which policies are current or what a customer was promised, has to come from an external system both agents query, typically over MCP.

3. Knowing whether a fact is still true. The SDK moves information; it does not adjudicate it. If the repository says one thing and a meeting decided another, the agent receives whichever surface it happened to read. Contradiction detection and time-awareness are properties of a memory layer, not of an agent framework.

This is the architectural line worth understanding before building: the SDK is the acting layer. The knowing layer, what is currently true across your company and who may see it, is a separate system. Sentra sits in that second layer, serving governed, time-stamped facts to SDK agents over MCP, which is why the two compose rather than compete.

How does it compare to the alternatives?

The honest reading: choose the Claude Agent SDK when you want Claude and you want the loop Anthropic already hardened. Choose a graph framework when your workflow must be deterministic end to end. Every option on this row leaves organizational memory as an exercise for the builder.

FAQ

The decision rule

Build on the Claude Agent SDK when you want a capable agent this week and are willing to let the model drive control flow. Before you scale past one agent, decide where shared knowledge lives, because the SDK deliberately does not answer that, and retrofitting a knowing layer after five agents have each built their own view of the company is the expensive path.