Claude Agent SDK: Build Agents on Claude Code's Harness (TypeScript + Python)

What the Claude Agent SDK Is

Claude Code is the agent that reads files, runs commands, searches code, and ships changes from your terminal. The Claude Agent SDK is that same agent exposed as a library. You get the agent loop, the built-in tools, and the context management that power Claude Code, programmable from your own code in Python and TypeScript.

The entry points are symmetric across languages. In Python you call query(prompt, options=ClaudeAgentOptions(...)). In TypeScript you call query({ prompt, options }). Both return an async iterable of messages that you iterate as the agent works through the task.

The defining property is that the SDK runs the loop. You hand it a task, and it decides which tool to call, calls it, reads the result, and continues until the work is done. You do not parse tool-call blocks or execute tools by hand. That responsibility moves from your code into the harness.

Renamed From Claude Code SDK

If you are searching for the "Claude Code SDK," this is the page. What shipped as the Claude Code SDK was renamed to the Claude Agent SDK in late 2025. The docs say it without ambiguity: "The Claude Code SDK is now the Claude Agent SDK."

The rename was not cosmetic. The package names changed, so old install commands no longer resolve. Anthropic links a migration guide that covers the breaking changes between the two. If you have code importing the old package, that guide is the path forward.

The reason for the rename is the scope. "Claude Code SDK" implied a coding-only tool. The same harness builds agents for support automation, data pipelines, research, and any multi-step task. "Agent SDK" names what it actually is: a general agent-building library that happens to ship the Claude Code tools.

Install: TypeScript and Python

The SDK ships as two packages, one per language. The install commands and verified package names are below.

The TypeScript package bundles a native Claude Code binary for your platform as an optional dependency. Claude Code does not need to be installed separately for the TypeScript SDK to run. This is a meaningful difference from the prior setup, where the CLI was a precondition.

Authentication is an API key. Set ANTHROPIC_API_KEY in the environment. The SDK also supports Amazon Bedrock, the Claude platform on AWS, Google Vertex AI, and Microsoft Azure through their respective environment variables, so the same agent code runs against whichever provider holds your Claude access.

What the SDK Provides

The SDK gives you Claude Code's harness, not just a model call. The pieces below ship in the box.

Because the tools ship built in, a fresh agent can read a file, run a shell command, or search the web on the first turn. There is no scaffolding step where you register handlers for each tool. That scaffolding is the bulk of the work when you build agents on the raw API, and the Agent SDK removes it.

A Minimal Agent

The smallest useful program installs the SDK, sets the API key, and iterates the message stream from query. The TypeScript and Python forms mirror each other.

// npm install @anthropic-ai/claude-agent-sdk
// Set ANTHROPIC_API_KEY in your environment.
import { query } from "@anthropic-ai/claude-agent-sdk";

// query returns an async iterable of messages.
// The SDK runs the agent loop and executes built-in
// tools (Read, Edit, Bash, Grep, ...) for you.
const response = query({
  prompt: "Find the failing test in this repo and fix it",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    permissionMode: "acceptEdits",
  },
});

for await (const message of response) {
  console.log(message);
}

# pip install claude-agent-sdk   (Python 3.10+)
# Set ANTHROPIC_API_KEY in your environment.
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    # query returns an async iterable of messages.
    # The SDK runs the agent loop and executes the
    # built-in tools for you.
    async for message in query(
        prompt="Find the failing test in this repo and fix it",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            permission_mode="acceptEdits",
        ),
    ):
        print(message)

anyio.run(main)

MCP, Subagents, Hooks, Permissions

Four systems carry over from Claude Code: the Model Context Protocol, subagents, hooks, and permissions. Each is configured through the same options object you pass to query.

Subagents are defined with AgentDefinition (a description, a prompt, and a tool list) and spawned through the Agent tool. The main agent delegates a focused subtask, the subagent works in its own context, and it reports the result back. This is the same hierarchy that lets Claude Code split a large task across multiple workers.

Hooks are where you enforce policy. A PreToolUse hook can block a dangerous command before it runs. A PostToolUse hook can log every edit. SessionStart and SessionEnd bracket a run for setup and teardown. The hook is your code, called at a fixed point in the loop.

MCP is how the agent reaches your stack. Point mcp_servers / mcpServers at a server and its tools become available to the agent alongside the built-in ones. Morph exposes its tools over MCP, which is the connection used in the Morph section below.

Agent SDK vs the Messages API

The most common point of confusion is which Anthropic surface to use. The Messages API (the Client SDK) is a single request/response call. The Agent SDK runs an autonomous loop on top of it.

Use the Messages API when you want one generation and full control over any tools, or when you are building a non-agentic feature like classification or summarization. Use the Agent SDK when the task is multi-step, file-touching, and you want the harness to drive: find the bug, fix it, run the tests, report back.

The tradeoff is control versus leverage. The Messages API gives you every decision and every line of dispatch code. The Agent SDK takes the loop, the tools, and the context management off your plate, at the cost of running Anthropic's harness rather than your own. For most agent workloads, that trade is worth it.

Common Use Cases

Anthropic recommends the SDK for CI/CD pipelines, custom applications, and production automation. The Claude Code CLI stays the better choice for interactive development and one-off tasks; the SDK is for embedding the agent in a system.

The thread through all three is autonomy under constraint. The agent decides the steps, but permissions bound the blast radius and hooks record what happened. That is the difference between a script you wrote and an agent you supervise.

Wiring Morph Into the Harness

Agents built on the Claude Agent SDK can call Morph tools and route model calls through Morph. Two integration points matter: the tools the agent uses, and the model behind the loop.

On the tool side, Morph exposes its products over MCP, so they slot into the SDK's mcp_servers / mcpServers option alongside the built-in tools. Fast Apply (morph-v3-fast, ~10,500 tok/s with speculative decoding) lands edits fast, and WarpGrep handles code search at $0 for the first 100k requests and $1 per 1M after. The agent calls them like any other tool.

On the model side, you can point the harness at a different model or route through Morph's model router. The router classifies prompt difficulty in ~430ms into four tiers and selects the cheapest model that fits, for 40-70% API cost savings at roughly $0.001 per classification, through one OpenAI-compatible API at api.morphllm.com. For running Claude Code itself against a non-Claude model, see use a different LLM with Claude Code.

import { query } from "@anthropic-ai/claude-agent-sdk";

// Expose Morph's Fast Apply + WarpGrep tools to the
// agent over MCP, alongside the built-in tools.
const response = query({
  prompt: "Search the repo for the auth handler and add rate limiting",
  options: {
    mcpServers: {
      morph: {
        // Morph MCP server endpoint (see docs.morphllm.com)
        command: "morph-mcp",
      },
    },
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
  },
});

for await (const message of response) {
  console.log(message);
}

Frequently Asked Questions

What is the Claude Agent SDK?

The Claude Agent SDK is a library that gives you the same agent loop, built-in tools, and context management that power Claude Code, programmable in Python and TypeScript. Unlike the Anthropic Client SDK (where you implement the tool loop yourself), the Agent SDK runs the loop with built-in tool execution for you. Its entry point is query, which returns an async iterable of messages.

Is the Claude Agent SDK the same as the Claude Code SDK?

Yes. The Claude Code SDK was renamed to the Claude Agent SDK in late 2025. The docs state it directly: "The Claude Code SDK is now the Claude Agent SDK." The package names changed and Anthropic links a migration guide for the breaking changes.

How do I install the Claude Agent SDK in TypeScript and Python?

TypeScript: npm install @anthropic-ai/claude-agent-sdk, which bundles a native Claude Code binary as an optional dependency, so Claude Code does not need to be installed separately. Python: pip install claude-agent-sdk, which requires Python 3.10 or later. Authenticate with the ANTHROPIC_API_KEY environment variable.

What can you build with the Claude Agent SDK?

Anthropic lists CI/CD pipelines, custom applications, and production automation as the recommended use cases, versus the Claude Code CLI for interactive development and one-off tasks. The built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, AskUserQuestion) let the agent read code, run commands, and search the web without you implementing tool execution.

Does the Claude Agent SDK support MCP, subagents, and hooks?

Yes. It connects to external systems via the Model Context Protocol using mcp_servers (Python) / mcpServers (TypeScript). Subagents are spawned via the Agent tool and defined with AgentDefinition. Hooks run custom callbacks at lifecycle points including PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, and UserPromptSubmit.

What is the difference between the Claude Agent SDK and the Messages API?

The Messages API (the Client SDK) is a single request/response call where you implement the tool-use loop yourself. The Agent SDK runs that loop for you with built-in tool execution, context management across turns, resumable sessions, and filesystem config from .claude/ and ~/.claude/. Use the Messages API for direct generation; use the Agent SDK for autonomous, multi-step work.

How does the Claude Agent SDK handle permissions and sessions?

Permissions are controlled by pre-approving tools via allowed_tools / allowedTools and modes such as acceptEdits. Sessions persist context across exchanges: capture a session_id from the init system message and resume with the resume option.

Related Resources

• Use a Different LLM With Claude Code
• Claude Code Models
• What Is an LLM Router?
• Multi-Agent Model Routing
• Fast Apply Model for Code Edits
• Best AI Model for Coding
• LLM API Comparison
• Anthropic API Pricing