Agent SDK overview

The Claude Agent SDK lets you run the same agent that powers Claude Code from inside your own Python or TypeScript program. You hand it a task, it plans the steps, calls tools (reading files, running shell commands, editing code, searching the web) and streams back everything it does until the job is finished.

An "agent" in this sense is just a program that works out its own route to a goal. You describe the outcome you want; the model decides which tools to call and in what order, looks at the results, and keeps going. The SDK supplies the loop, the built-in tools, context management, permissions and session handling, so you only write the bit that is specific to your product.

I reach for it when a workflow I have proven interactively in Claude Code needs to run unattended: a nightly dependency audit, a bot that triages support tickets, or a review step inside a client's deployment pipeline.

Choosing between the SDK and other options

There are four common ways to put Claude to work in code. The right one depends on who runs the loop and how much you want built in.

If your stack is in another language entirely, you can still get the same loop by calling the CLI as a subprocess with -p and --output-format json. The headless guide covers that route.

What you can use from Claude Code

Almost everything you know from the CLI carries across. Each item has its own page in this handbook.

• Built-in tools. Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch and the rest. See the tools reference.
• Hooks. Callbacks that fire at points in the loop, for example before a tool runs. See SDK hooks.
• Subagents. Focused helpers the main agent can delegate to. See subagents.
• MCP servers. External tools and data over the Model Context Protocol. See MCP in the SDK.
• Permissions. Rules and modes that decide what runs automatically and what needs approval. See SDK permissions.
• Sessions. Conversations you can continue, resume later or fork. See sessions.
• Skills, commands and memory. Loaded from .claude/ in the project and from ~/.claude/, just as the CLI does. See skills, system prompts and CLAUDE.md and Claude Code features in the SDK.
• Plugins. Bundles of skills, agents, hooks and MCP servers loaded from a local path. See SDK plugins.

Packages and installation

Both packages ship a native Claude Code binary, so in most cases you do not need a separate Claude Code install. The quickstart explains the exceptions.

A taste of the API

The entry point in both languages is query(). It returns an async iterator of messages, ending with a result.

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

for await (const msg of query({
  prompt: "List every TODO comment under src/ and group them by file",
  options: { allowedTools: ["Grep", "Read"] },
})) {
  if (msg.type === "result" && msg.subtype === "success") {
    console.log(msg.result);
  }
}

That is a working agent. Everything else (custom tools, hooks, structured output, sessions) is configuration layered on top.

Authentication and terms

Use an Anthropic API key (ANTHROPIC_API_KEY) or one of the cloud providers: Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform (Vertex AI) or Microsoft Foundry. The quickstart lists the environment variables.

Note: Unless Anthropic has approved it in advance, third-party products built on the SDK may not offer claude.ai login or claude.ai rate limits to their users. Authenticate with API keys or a cloud provider instead.

Use of the SDK is covered by Anthropic's Commercial Terms of Service, including when the agent powers a product you sell to your own customers. Individual dependencies may carry their own licence files.

Naming your product

If you are building a product on the SDK, you can mention Claude, but your product must keep its own identity.

• Acceptable: "Claude Agent" (good for a dropdown), "Claude" inside a menu already labelled "Agents", or "YourAgent Powered by Claude".
• Not acceptable: calling it "Claude Code" or "Claude Code Agent", or using Claude Code ASCII art and visuals that make your tool look like an Anthropic product.

Changelogs and bug reports

Each SDK lives in its own GitHub repository, where you will find the changelog and the issue tracker:

• TypeScript: anthropics/claude-agent-sdk-typescript
• Python: anthropics/claude-agent-sdk-python

Demo applications (an email assistant, a research agent and others) are in anthropics/claude-agent-sdk-demos.

Related

• Agent SDK quickstart
• How the agent loop works
• Configure your agent
• Migrating from the Claude Code SDK
• TypeScript SDK reference