Building on Claude
The Claude Agent SDK: building agents on Claude
The Claude Agent SDK is Anthropic's library for building AI agents on the same harness that powers Claude Code — the agent loop, built-in tools, context management, and an MCP, subagent, hooks, permissions, and sessions toolkit — programmable in Python and TypeScript. It was renamed from the Claude Code SDK because the same harness builds agents for far more than coding. Instead of hand-writing a tool-execution loop, you describe a goal and the SDK runs Claude until the task is done.
This page explains what the SDK is and what it gives you. For the orchestration picture around it, see agentic AI architecture; for where the agent process actually runs, see where to run Claude agents.
What is the Claude Agent SDK?
The Claude Agent SDK is a library that gives you Claude with built-in tool execution. Anthropic describes it as Claude Code as a library: the same tools, agent loop, and context management that power the Claude Code CLI, exposed so you can build your own agents on top of them. It is available as the TypeScript package @anthropic-ai/claude-agent-sdk and the Python package claude-agent-sdk (Python 3.10+).
It evolved from the Claude Code SDK, which Anthropic renamed to the Claude Agent SDK. The old name implied a coding-only tool; the same harness builds support automation, research agents, data pipelines, and any multi-step task, so the new name reflects what it actually is — a general agent-building library that happens to ship the Claude Code tools. The Python options type was renamed in step, from ClaudeCodeOptions to ClaudeAgentOptions.
The core idea is the agent loop. With the direct API you send a prompt, inspect the stop reason, run any requested tool yourself, feed the result back, and repeat. The Agent SDK runs that loop for you: Claude reads files, runs commands, searches, and edits code autonomously, streaming each message back as it goes.
What the Claude Agent SDK gives you
Everything that makes Claude Code capable is available through the SDK. These are the documented building blocks — the parts you compose into an agent rather than implement from scratch.
| Capability | What it provides |
|---|---|
| Agent loop | Runs the read-decide-act loop for you — Claude calls tools and you receive streamed messages, with no hand-written tool-execution loop. |
| Built-in tools | Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, and more, ready to use out of the box so the agent can act immediately. |
| Subagents | Spawn specialised sub-agents with their own instructions, tools, and context; the main agent delegates focused subtasks and they report back. |
| MCP | Connect external systems — databases, browsers, APIs — over the Model Context Protocol, alongside the built-in tools. |
| Hooks | Run custom code at lifecycle points (PreToolUse, PostToolUse, SessionStart, SessionEnd, and more) to validate, log, block, or transform behaviour. |
| Permissions | Control exactly which tools the agent can use — allow safe operations, block dangerous ones, or require approval for sensitive actions. |
| Sessions | Maintain context across exchanges; capture a session id, then resume it later or fork it to explore a different approach. |
| Context management | The same context handling that keeps Claude Code working across long tasks, inherited by your agent. |
| Claude Code config | Loads filesystem configuration from .claude/ — skills, slash commands, CLAUDE.md memory, and plugins — controllable via the setting-sources option. |
Authentication is via an Anthropic API key by default, and the SDK also supports Amazon Bedrock, the Claude Platform on AWS, Google Vertex AI, and Microsoft Azure as providers — so the same agent code can run against a model hosted in your own cloud.
Claude Agent SDK vs building it yourself
The alternative is the Anthropic Client SDK (the direct Messages API). It gives you raw model access: you send prompts and implement tool execution yourself. That means writing and maintaining the loop — check the stop reason, dispatch the tool, marshal the result back, handle errors, manage context as it grows.
The Agent SDK collapses that into one call. You hand it a goal and an allowed-tools list, and Claude handles the tool calls autonomously while you consume streamed messages. The trade is control for leverage: the Client SDK is the right choice when you need a bespoke loop or a single completion; the Agent SDK is the right choice when you want the proven Claude Code harness — tools, context management, sessions, permissions — without rebuilding it. For the loop itself in depth, see agentic AI architecture.
Claude Agent SDK vs other frameworks
Framework-agnostic libraries such as LangGraph give you a graph or state machine for orchestrating steps across any model provider. The Claude Agent SDK is narrower and deeper: it is Anthropic's own harness, tuned for Claude, shipping a batteries-included tool layer (filesystem, shell, web, MCP) plus subagents, hooks, and sessions that a generic framework leaves you to assemble.
Pick the SDK when Claude is your model and you want the same agent that powers Claude Code, with minimal wiring. Pick a framework when you need provider portability, an explicit graph you fully own, or orchestration spanning several model vendors. The two are not mutually exclusive — you can run the Agent SDK as a node inside a larger framework-driven flow. For the wider landscape, see AI agent frameworks compared.
Getting started with the Claude Agent SDK
Install the SDK, set an API key, and run a query. In TypeScript:
- Install —
npm install @anthropic-ai/claude-agent-sdk(the package bundles a native Claude Code binary, so you do not install Claude Code separately). For Python,pip install claude-agent-sdk. - Authenticate — set
ANTHROPIC_API_KEYfrom the Console, or configure a Bedrock, AWS, Vertex, or Azure provider via the documented environment variables. - Run — call
querywith a prompt and anallowedToolslist, then iterate the async stream of messages until the result arrives.
A first agent can be as small as find and fix the bug in auth.ts with allowedTools of Read, Edit, and Bash — Claude reads the file, finds the bug, and edits it. From there you add MCP servers, subagents, hooks, and permissions as the task demands. Once it works, decide where the agent process should live; that deployment question is its own decision, covered in where to run Claude agents.
Frequently asked questions
What is the Claude Agent SDK?
It is Anthropic's library for building AI agents on the same harness that powers Claude Code — the agent loop, built-in tools (Read, Write, Edit, Bash, Glob, Grep, web search), context management, MCP, subagents, hooks, permissions, and sessions. Instead of implementing a tool-execution loop against the raw API, you give it a goal and it runs Claude autonomously until the task is done. It is available in Python and TypeScript.
Is the Claude Agent SDK the same as the Claude Code SDK?
Yes — it is the Claude Code SDK renamed. Anthropic renamed it to the Claude Agent SDK because the same harness builds agents for far more than coding (support automation, research, data pipelines), and the coding-only name no longer fit. Practically, the package names changed and the Python options type was renamed from ClaudeCodeOptions to ClaudeAgentOptions; a migration guide covers the move.
What languages does the Claude Agent SDK support?
Python and TypeScript. The TypeScript package is @anthropic-ai/claude-agent-sdk (installed with npm); the Python package is claude-agent-sdk (installed with pip and requiring Python 3.10 or later). Both expose the same agent loop and capabilities.
What does the Claude Agent SDK do?
It runs the agent loop for you: Claude reads files, runs commands, searches the web, and edits code autonomously, streaming each step back. On top of that it provides built-in tools, subagents, MCP connectivity, lifecycle hooks, fine-grained tool permissions, and resumable sessions — plus Claude Code filesystem config like skills, slash commands, CLAUDE.md memory, and plugins.
Claude Agent SDK vs LangGraph?
LangGraph is a provider-agnostic orchestration framework — you build an explicit graph or state machine across any model. The Claude Agent SDK is Anthropic's own harness, tuned for Claude, with a batteries-included tool layer plus subagents, hooks, and sessions out of the box. Choose the SDK when Claude is your model and you want minimal wiring; choose a framework for provider portability or a graph you fully own. They can also be combined.
How do you get started with the Claude Agent SDK?
Install the package (npm install @anthropic-ai/claude-agent-sdk or pip install claude-agent-sdk), set ANTHROPIC_API_KEY (or configure Bedrock, AWS, Vertex, or Azure), then call query with a prompt and an allowed-tools list and iterate the streamed messages. A first agent can simply find and fix a bug with Read, Edit, and Bash, then grow with MCP servers, subagents, and hooks.
- Agent SDK overview, capabilities, packages, and provider auth: Anthropic, Agent SDK overview (Claude Code / Claude Platform docs).
- Rename from the Claude Code SDK and the
ClaudeCodeOptions→ClaudeAgentOptionschange: Anthropic, Migrate to the Claude Agent SDK. - Language references: TypeScript SDK and Python SDK reference docs.
SDK package names, options, and capabilities change; verify exact signatures against the live docs above before building. Corrections: hello@aiarch.dev.
Learn to build agents on Claude — by building one.
AI Architect Academy teaches the agent loop, tools, MCP, memory, and the operational plane as first-class skills, on a platform that is itself a production agentic system built across Anthropic, AWS, and Cloudflare. The build is the curriculum.
Free sample — no signup · every claim cited · cancel anytime
Or get notified when new tracks ship.