Claude Agent SDK

What you get that a hand-written loop does not

Writing an agent loop is not hard. Send a message, check whether the model asked for a tool, run it, send the result back, repeat until it stops asking.

The loop is the easy part. What takes the time is everything around it: managing context as the conversation grows, deciding which tools run without asking, resuming a session tomorrow, and the file and shell tools you end up writing because every agent needs them.

Anthropic's Agent SDK is that surrounding work, extracted. The documentation describes it as giving you "the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript." It is a harness that already runs a production agent, offered as a library.

What the harness provides

Sessions and context management are the entries that justify the dependency. Both are where a hand-written agent starts accumulating code that has nothing to do with your problem.

Permissions come before features

An agent with file and shell access can modify anything the process can reach. The permission model decides which tools run automatically and which stop for approval, and it is the first thing to configure rather than the last.

Decide two things before the first run. What the agent may touch, which is a question about the working directory and the credentials in its environment. And which actions proceed without asking, which is a question about how much review you want.

The economics are the opposite of most configuration. Getting this wrong is not a bug you fix after noticing; it is a command that already ran. Start strict and loosen as you learn what the agent does with a task, rather than starting permissive and tightening after something surprises you.

Extending the agent with tools you did not write

The SDK connects to MCP servers, which is how an agent reaches things outside its built-in toolset: your ticket system, your database, your internal APIs.

That inherits the trust position MCP has. An MCP server's output lands in the model's context, so a server over content you do not control is a path for instructions you did not write. The permission model is what contains it, which is another reason to configure it first.

Hooks and subagents cover the rest of the extension surface. Hooks run your code at lifecycle points, which is where logging, policy checks and custom guardrails belong. Subagents hand a focused task to a fresh context and return a condensed result, keeping detail out of the main thread.

Choosing the SDK against the CLI or a hosted agent

Anthropic's own comparison separates four things worth keeping straight:

• The Agent SDK, for building an agent without writing the loop.
• The Claude Code CLI, for interactive terminal work and one-off tasks.
• The Client SDK, for calling the API directly and writing the loop yourself.
• Managed Agents, a hosted product where Anthropic runs the agent and the sandbox.

Two constraints belong in the decision. The library is Python and TypeScript only; other languages drive the same loop by running the CLI as a subprocess with -p and --output-format json. And there is a licensing condition: third-party developers may not offer claude.ai login or rate limits for products built on the SDK without prior approval, so plan on API key authentication.

Write the loop yourself when your agent is a narrow tool with two or three functions and you want no dependency between you and the API. Take the harness when you need file access, sessions, and permissions, which is most of the time.

Further reading

• Anthropic, Agent SDK overview: capabilities, the comparison table, and the language constraint.
• Anthropic, Building effective agents: when a loop earns its cost.
• Function calling: the round trip every harness runs for you.