Claude Agent SDK: install it, build an agent, and control tools, permissions, MCP, skills and sessions

What is the Claude Agent SDK?

The Claude Agent SDK is Anthropic's library for building AI agents in Python or TypeScript on top of Claude Code. Anthropic's overview says it "gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript." You hand it a prompt, and the agent reads files, runs commands, edits code and searches the web until the task is done, while your code streams each step.

It used to be called the Claude Code SDK. Anthropic renamed it to reflect that the SDK builds agents for tasks beyond coding. The migration guide lists the old packages, @anthropic-ai/claude-code and claude-code-sdk, and their replacements.

How is it different from the Claude API and the CLI?

Anthropic offers four ways to run Claude as an agent, and the right one depends on who runs the loop:

The practical difference from the Client SDK is tool execution. With the raw API, Claude asks for a tool call and your code has to run it and send back the result. With the Agent SDK, Claude executes built-in tools like Read, Edit and Bash directly. The quickstart says it plainly: "Claude executes tools directly instead of asking you to implement them."

If you need another language, the docs suggest running the CLI as a subprocess with -p and --output-format json.

How do you install the Claude Agent SDK?

You need Node.js 18 or later, or Python 3.10 or later, and an Anthropic account. Install the package for your language:

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python with uv
uv add claude-agent-sdk

# Python with pip (inside a virtual environment)
pip install claude-agent-sdk

Both packages bundle a native Claude Code binary, so most installs need nothing else. Two exceptions from the quickstart: a Python source install with no platform wheel (for example on ARM64 Windows), and an npm install that skips optional dependencies, such as npm ci --omit=optional. In both cases, install Claude Code natively.

Then set an API key from the Claude Console:

export ANTHROPIC_API_KEY=your-api-key

The SDK reads the key from the process environment and does not load .env files on its own, so load them yourself with something like dotenv. It also works through cloud providers: set CLAUDE_CODE_USE_BEDROCK=1 for Amazon Bedrock, CLAUDE_CODE_USE_VERTEX=1 for Google Cloud's Agent Platform, or CLAUDE_CODE_USE_FOUNDRY=1 for Microsoft Foundry, then configure that provider's credentials.

One rule matters if you ship a product. The docs state: "Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK." Your users' agents run on API keys, not on a Pro or Max subscription.

How do you build your first agent?

The quickstart builds an agent that finds and fixes bugs in a file. The core is one query() call:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")


asyncio.run(main())

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

for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits"
  }
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
      else if ("name" in block) console.log(`Tool: ${block.name}`);
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`);
  }
}

There are three parts. query creates the agent loop and returns an async iterator. prompt is the task. options configures the agent: here allowedTools pre-approves three tools and permissionMode: "acceptEdits" auto-approves file edits. Other options include systemPrompt and mcpServers.

Each loop iteration yields a message: Claude's reasoning, a tool call, a tool result or the final result. The SDK handles orchestration, tool execution, context management and retries. Run it with npx tsx agent.ts, uv run agent.py or python agent.py.

Which tools can the agent use?

The SDK ships Claude Code's built-in tools, listed in the tools reference. The quickstart groups common sets like this:

Add WebSearch for web search, Bash to run commands such as a test suite, or Agent to spawn subagents for focused subtasks. You can also write your own tools: define one with the @tool decorator in Python or tool() in TypeScript, then wrap it with create_sdk_mcp_server or createSdkMcpServer. That server runs in-process inside your app rather than as a separate process.

How do permissions work in the Agent SDK?

Permissions decide which tool calls run on their own and which need a decision. The permissions page describes a fixed order for every request:

1. Hooks run first and can deny a call outright.
2. Deny rules from disallowed_tools and settings block a match, even in bypassPermissions mode.
3. Ask rules send the call to your canUseTool callback.
4. Permission mode applies its auto-approvals.
5. Allow rules from allowed_tools and settings approve a match.
6. canUseTool decides anything still unresolved.

The modes are default, dontAsk (deny instead of prompting), acceptEdits, bypassPermissions, plan (explore and plan without editing source files) and auto (a model classifier reviews actions). For a locked-down agent, the docs pair allowedTools with permissionMode: "dontAsk", so listed tools run and anything else that would prompt is denied.

Two traps are worth knowing. First, allowed_tools does not limit bypassPermissions: unlisted tools fall through to the mode, which approves them, so use disallowed_tools to block things. Second, a call approved by an earlier step never reaches canUseTool, so checks that must run on every call belong in a PreToolUse hook.

How do you connect MCP servers?

The Model Context Protocol lets your agent use outside tools like databases, browsers and APIs. Pass servers in the mcpServers option, either as a local process with command and args or as a remote server with "type": "http" and a url. You can also keep them in a .mcp.json file loaded through settingSources.

MCP tool names follow the pattern mcp__<server>__<tool>. To pre-approve every tool from one server, add a wildcard such as mcp__github__* to allowedTools. An unanchored entry like mcp__* is ignored in allow rules. The SDK MCP guide covers transports, auth and tool search for large tool sets, and the Claude Code MCP guide covers the CLI side.

How do skills work with the Agent SDK?

Skills are SKILL.md folders that Claude loads when a task matches their description, the same Agent Skills format Claude Code uses. In the SDK, skills live on disk only. The skills page notes there is no programmatic API for registering them.

With default options, the SDK loads user and project settings, so skills in ~/.claude/skills/ and .claude/skills/ are available. If you set settingSources yourself, include "project" and "user" to keep them. The skills option controls which ones Claude may invoke: a list of names such as ["pdf", "docx"], "all", or [] for none. You can also run a skill by sending /<name> in the prompt.

How do sessions work?

A session is the conversation history the agent builds up: your prompt, every tool call, every result and every response. The SDK writes it to disk so you can return to it. Three options control that, per the sessions page:

• Continue picks up the most recent session in the current directory, with no ID to track.
• Resume takes a specific session ID, read from the session_id field on the result message. Use it for multi-user apps or to retry after hitting a turn or budget limit.
• Fork starts a new session from a copy of the original's history and leaves the original unchanged.

In Python, ClaudeSDKClient keeps one session across several client.query() calls. In TypeScript, pass continue: true on later query() calls. Sessions store the conversation, not your files, so use file checkpointing if you need to roll back edits.

Keep your agent's skills in one place

Agents built on the SDK read the same SKILL.md format as Claude Code, so a skill library pays off twice. Kipt stores your prompts and Agent Skills as Markdown in a private GitHub repo you own, and npx skills add https://github.com/<you>/<repo>.git --all -g installs every skill into Claude Code or Codex. To turn a prompt into a skill quickly, the free SKILL.md generator runs in your browser with no sign-up.