Claude Code SDK: the current Claude Agent SDK guide

Summary

Start with one narrow task in an isolated test directory. Install the current TypeScript or Python package. Authenticate with an approved API-key method and stream the agent's messages. Grant only the tools and files the task needs. Add approval gates, sandboxing, network controls, credential separation, time and cost limits, structured outcomes, logs, tests, and human review before production.

What is the Claude Code SDK?

The term Claude Code SDK means the earlier name for Claude Agent SDK. A search for Claude SDK may also refer to this library or to Anthropic's lower-level client SDKs. Anthropic says the rename reflects uses beyond coding. The current library runs the Claude Code-style agent loop in a process that your team operates. It can read streamed messages, use built-in tools, connect MCP tools, manage sessions and context, use hooks, create subagents, track usage, and expose observability.

Check Anthropic's current migration guide for the rename and breaking changes.

Choose the right Claude tool

Claude Agent SDK

use it when your Python or TypeScript process should run the agent loop and Claude Code tools.

Claude Code CLI

use it for interactive development and one-off terminal tasks rather than embedding an agent in a product.

Anthropic client SDK

use it to call the Messages API directly when your application will implement the tool loop, state, retries, and orchestration.

Claude Managed Agents

use the separate hosted product when Anthropic should run the agent and sandbox for long-running or asynchronous work.

CLI subprocess

use `claude -p` with JSON output when another programming language must drive the same loop and a supported library is unavailable.

See the official Agent SDK comparison and capability overview.

When the Agent SDK is a good fit

• A coding agent must inspect files, edit a controlled workspace, run tests, and report a verifiable result.
• A support or operations agent needs a loop that plans, calls approved tools, observes results, and continues within fixed limits.
• A team wants Claude Code capabilities such as sessions, hooks, MCP, subagents, skills, structured output, and checkpointing in its own process.
• The application can accept a Claude-specific runtime and the team can own isolation, permissions, credentials, deployment, monitoring, and incident response.

A single API call, deterministic script, queue worker, search query, or form workflow may solve the task without an autonomous loop. Avoid the SDK when provider portability is a firm requirement and the application cannot isolate Claude-specific behavior behind its own boundary.

Set up a small Agent SDK project

1. 1Create an empty test directory with no credentials, production data, or unrelated repositories.
2. 2Use Node.js 18 or later for TypeScript, or Python 3.10 or later for Python, as required by the current quickstart.
3. 3Install `@anthropic-ai/claude-agent-sdk` in a TypeScript project or `claude-agent-sdk` in an isolated Python environment.
4. 4Provide `ANTHROPIC_API_KEY` through the running process or configure a supported cloud provider. Keep keys out of source and load any `.env` file explicitly.
5. 5Call the SDK's query interface with a narrow prompt, an explicit working directory, bounded turns, and the smallest useful tool set.
6. 6Consume streamed message types and record the final result, errors, tool activity, duration, usage, and application trace identifier.
7. 7Inspect every file and command change, run deterministic tests, remove the test credentials, and delete the isolated workspace when finished.

Use Anthropic's current Python and TypeScript quickstart for exact package and API syntax.

Understand the bundled Claude Code binary

The current quickstart says both supported SDKs normally bundle a native Claude Code binary. A Python source distribution or a TypeScript install that omits optional dependencies may not include it. Production builds should verify the package, binary, platform, lockfile, checksum process, and startup behavior instead of relying on a developer machine's global installation.

Use an approved authentication method

Anthropic's quickstart supports an Anthropic API key and documented cloud-provider paths. It also says third-party developers may not offer claude.ai login or subscription rate limits in their products unless Anthropic approved them. Treat a user's Claude subscription and a product's SDK authentication as separate decisions.

Design permissions before tools

The quickstart's `allowedTools` or `allowed_tools` list pre-approves named tools; it is not a complete sandbox. An unlisted tool can still pass through other permission logic. Define which tools exist, which calls are allowed, blocked, or reviewed, which paths are readable or writable, and which actions need a person. Test denials and malformed requests as carefully as successful calls.

Follow the current Agent SDK permission evaluation order.

Secure the runtime around the agent

An agent can be influenced by files, webpages, tool results, and user input. Anthropic's deployment guide treats prompt injection and model error as reasons for defense in depth. The application remains responsible for the boundary around the agent.

Filesystem

mount only the required project, prefer read-only input, and provide a small disposable write area.

Network

deny access by default and allow only required destinations through a controlled proxy.

Credentials

keep secrets outside the agent boundary and let a proxy inject or exchange them for narrow operations.

Process

run without root, limit CPU, memory, time, process count, output, and concurrent tasks.

Tools

validate inputs, enforce policy in code, log decisions, and require approval for destructive or external actions.

Data

classify inputs and outputs, minimize retention, prevent cross-tenant context, and redact sensitive logs.

Recovery

keep immutable source, checkpoints, backups, idempotent actions, cancellation, and a tested incident path.

Use Anthropic's secure deployment guide to match isolation to the threat model.

Production readiness checklist

• A bounded task, success condition, failure condition, and escalation owner are documented.
• Tool schemas, permission rules, approval paths, settings sources, and system prompts are explicit and tested.
• Untrusted content, prompt injection, data leakage, excessive actions, and tool failures have adversarial tests.
• The sandbox, filesystem, network, credentials, cloud roles, and tenant boundaries match the threat model.
• Sessions, retries, timeouts, cancellation, idempotency, queues, and concurrency limits have owners.
• Cost, tokens, latency, tool use, errors, outcomes, traces, and human overrides are monitored.
• Model, SDK, bundled binary, dependencies, and settings changes pass a fixed evaluation set before rollout.
• A person can inspect, stop, roll back, and explain every material external action.

Set budgets with the official usage and cost tracking guidance.

Migrate from the old Claude Code SDK

1. 1Replace `@anthropic-ai/claude-code` with `@anthropic-ai/claude-agent-sdk` in TypeScript. Replace `claude-code-sdk` with `claude-agent-sdk` in Python.
2. 2Update imports and rename Python `ClaudeCodeOptions` to `ClaudeAgentOptions`.
3. 3Check the system prompt change: the current Agent SDK uses a minimal prompt unless the Claude Code preset or a custom prompt is requested.
4. 4Review settings sources explicitly. Current default behavior can load user, project, local settings, CLAUDE.md files, and commands; isolated workloads should choose sources deliberately.
5. 5Run security, behavior, cost, and regression tests against the locked new package and bundled binary before rollout.

What current SDK guides emphasize

Current tutorials emphasize installation, a short query example, permissions, scripts, CI, and custom tools. Framework comparisons add feature grids for MCP, hooks, sessions, tracing, subagents, languages, and provider lock-in. This guide keeps that coverage. It also makes the rename, authentication, inherited settings, bundled binary, threat model, isolation, approval, cost, and operations explicit.

Compare current agent-framework coverage from Morph as third-party research.

Install the interactive CLI with the Claude Code setup guide.

Read the Claude Code subagents guide before adding task delegation.

Frequently asked questions