Claude Agent SDK: what it is, how to install it and a first working agent

What is the Claude Agent SDK?

The Agent SDK overview describes an agent as an application that completes a task by planning its own steps and calling tools that read files, run commands or edit code. The SDK hands you that machinery as a library. You write a short script, pass it a prompt, and the same loop that runs inside the Claude Code terminal app runs inside your program: Claude decides which tool to call, the SDK runs it, the result goes back to Claude, and this repeats until the task is done.

That is different from calling the Claude API directly. With the plain API you write the tool loop yourself, or let a tool runner drive it. With the Agent SDK the file reading, file editing, shell commands, web search, permission checks and conversation history are already built, because they are the parts of Claude Code that Anthropic exposes as a library. According to the overview page, the SDK runs the Claude Code binary underneath, and both the TypeScript and Python packages bundle a native copy of it.

If you only want to use Claude Code to build things, you do not need the SDK at all. Start with the Claude Code tutorial or the guide to building an app with Claude Code. The SDK is for the case where you want an agent to be a feature of your own software: a nightly job that triages issues, a support tool that answers from your files, a script in CI that reviews a pull request.

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

Yes. Anthropic's migration guide says the Claude Code SDK was renamed the Claude Agent SDK, and that the change reflects the SDK's broader use for building agents beyond coding tasks. Old tutorials still use the old names, so the table below maps them.

The same guide lists the behavior changes that arrived with v0.1.0. The SDK no longer uses Claude Code's system prompt by default; it starts from a minimal one. To get the old behavior you pass the preset explicitly, for example systemPrompt: { type: "preset", preset: "claude_code" } in TypeScript, or write your own system prompt string. The guide also states the current rule for filesystem settings: if you omit settingSources, the SDK loads user, project and local settings, including CLAUDE.md files, as the CLI does. To run isolated from those files, pass an empty list. That matters for CI, deployed apps and anything multi-tenant, where one machine's personal settings should not leak into another run.

To migrate an old project, uninstall the old package, install the new one, change the imports and rename the options class. The guide gives the exact commands for npm and pip.

How do you install the Claude Agent SDK?

The quickstart lists two prerequisites: Node.js 18.14 or newer, or Python 3.10 or newer, and an Anthropic account to get an API key from the Claude Console. Then pick your language.

mkdir my-agent
cd my-agent
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

# uv
uv init
uv add claude-agent-sdk

# pip (macOS or Linux)
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Setting "type": "module" in package.json lets your script use top-level await, and tsx runs TypeScript files directly. You do not need to install Claude Code separately in most cases, because both packages ship a native binary. The quickstart names two exceptions: if pip installs the source distribution instead of a platform wheel (for example on ARM64 Windows), or if an npm install skipped optional dependencies. In those cases, install Claude Code natively, and for TypeScript set pathToClaudeCodeExecutable to its path.

Authentication is an environment variable. Run export ANTHROPIC_API_KEY=your-api-key on macOS or Linux, or set $env:ANTHROPIC_API_KEY in PowerShell. The SDK reads it from the process environment and does not load .env files, so load the file yourself with a package such as dotenv if you keep the key there. The docs also list Amazon Bedrock (CLAUDE_CODE_USE_BEDROCK=1), Google Cloud's Agent Platform (CLAUDE_CODE_USE_VERTEX=1) and Microsoft Foundry (CLAUDE_CODE_USE_FOUNDRY=1) as alternative routes, each with its own credentials. Never commit the key to a repository.

What does a minimal Claude Agent SDK example look like?

The quickstart builds an agent that finds and fixes bugs in a file. Create a small utils.py with a function that divides by len(numbers) and another that calls user["name"].upper(), both of which can crash. Then save the script below as agent.ts. It is trimmed from the official example; the full version prints more detail.

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 === "result") {
    console.log("Done: " + message.subtype);
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, 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, ResultMessage):
            print("Done:", message.subtype)


asyncio.run(main())

Run it with npx tsx agent.ts, or uv run agent.py, or python agent.py inside your virtual environment. The docs say the agent reads utils.py, analyzes the logic, edits the file to handle the empty list and the missing user, and ends with Done: success.

Three pieces do the work. query is the entry point that creates the agent loop. It returns an async iterator, so you stream messages as Claude works. prompt is the task, and Claude chooses its own tools. options is the configuration: allowedTools pre-approves tools so they run without asking, and permissionMode: "acceptEdits" auto-approves file edits. Other options include systemPrompt and mcpServers.

Which tools and permission settings should a first agent get?

The tools you list decide what the agent can do, so start with the smallest set that finishes the task. The quickstart groups them like this.

Adding Bash is where an agent stops being a reader and becomes something that can run any command your account can run. Give it that only inside a folder you can afford to lose, or inside a container, and read the permissions page first. It explains the order in which the SDK evaluates a tool call: hooks first, then deny rules, then ask rules, then the active permission mode, and finally a canUseTool callback you write yourself. A deny rule wins even in bypassPermissions mode.

What can the Agent SDK do beyond query?

The overview lists the Claude Code capabilities that are available in the SDK. Each links to its own page in the docs.

Sessions deserve one warning from the docs: they save the conversation, not the filesystem. If the agent changes files and you want to undo that, use the SDK's file checkpointing. For the concepts behind hooks, skills and subagents as they work in the terminal app, see the pages on Claude Code hooks, skills and subagents. The SDK uses the same ideas.

To drive the agent from another language, the overview says to run the CLI as a subprocess with the -p flag and --output-format json. The Anthropic site also links a repository of demo agents you can read and run locally.

What are the rules and limits of building on the SDK?

• Sign-in rule. The docs say that, unless previously approved, Anthropic does not allow third-party developers to offer claude.ai login or rate limits in their products, including agents built on the SDK. Use API key authentication for anything you ship.
• Branding rule. Partners may call a product "Claude Agent", or "{YourAgentName} Powered by Claude". The docs do not permit "Claude Code" or "Claude Code Agent", or visuals that mimic Claude Code. Your product should keep its own branding.
• Terms. Use of the SDK is governed by Anthropic's Commercial Terms of Service, including when it powers products you offer to your own customers.
• Cost. Installing the package is free; the model calls the agent makes are billed to the account behind your API key. Agents loop, so a vague prompt with Bash enabled can spend more than you expect. Set a narrow task, a small tool list, and check the Usage page in the Claude Console after the first runs, before you let a script run unattended.

Anthropic's pages change often, and this page describes them as of October 2026. Check the overview for the current rules before you launch something public.

What should you build with the Agent SDK first?

Start with an agent whose output you can check in a minute. Four that fit a first weekend:

• A repository explainer. Read-only tools, one prompt: summarize this project's structure and list the three files a new contributor should read first. The output is text, so a wrong answer costs nothing.
• A changelog writer. Run it in CI after a merge. It reads the git log through Bash, drafts release notes, and writes one Markdown file. Commit the file for a human to edit.
• A docs answerer. Point Read and Grep at a folder of Markdown and have the agent answer only from those files, and say so when the answer is not there. A board idea posted on this site describes this shape: An agent that answers from your docs and shuts up otherwise.
• A pull-request reviewer. Read-only, with a fixed checklist in the system prompt. Have it output a list of concerns rather than edit anything.

If you are short of ideas, browse AI agent ideas on the board. Every idea there has a generated build prompt you can paste into Claude Code, which can scaffold an SDK project for you. Here is a brief to start from.

Create a small TypeScript project that uses @anthropic-ai/claude-agent-sdk.

Goal: a command-line script that takes a folder path and a question, then answers the question using only the files in that folder.

Rules:
- Use query() from the SDK. Allow only the Read, Glob and Grep tools.
- Do not allow Edit or Bash.
- The system prompt must tell the agent to answer only from the files and to say 'not found in these files' when the answer is missing.
- Read ANTHROPIC_API_KEY from the environment. Do not hard-code or print it.
- Print only the final answer text.

Give me the package.json, the script, and the exact commands to run it. Then run it on this repository and show me one example answer.