skip to content

Agent SDK

The Agent SDK runs Claude Code's loop, tools and permission checks from Python or TypeScript, with approval callbacks and in-process custom tools. Asked because it is the library-or-CLI choice.

part ofClaude Coderead it →
on this pageshow

explore

questions

6

What is the Claude Agent SDK, and when would you embed it in an application instead of scripting `claude -p`?

level: juniorimportance: must knowfreq 15%

answer

  1. same loop, packaged as a library
  2. two packages, one per language
  3. renamed from the Claude Code SDK
  4. bundles a native Claude Code binary
  5. callbacks need a host process

basics

~20 s

The Claude Agent SDK runs Claude Code's agent loop, built-in tools, permissions, hooks and sessions as a Python or TypeScript library. Embed it when your service needs approval callbacks, in-process custom tools or typed messages; script claude -p for shell jobs.

solid answer

~50 s

The Agent SDK (`@anthropic-ai/claude-agent-sdk` for TypeScript, `claude-agent-sdk` for Python, renamed from the Claude Code SDK) gives your own code the same tools, agent loop and context management that power Claude Code. It does not reimplement that loop: both packages normally bundle a native Claude Code binary and drive it, so you get `Read`, `Edit`, `Bash` and the other built-in tools, permission rules, hooks, sessions and the `.claude/` configuration. You call `query()` and iterate typed messages until a result message arrives. Choose it over `claude -p` when the agent lives inside a service you operate and you need what a flag cannot express: a `canUseTool` approval callback, hook callbacks in your own process, custom tools built with `tool()` and `createSdkMcpServer`, or sessions you resume and fork from code. From any other language, the docs point you to `claude -p` with JSON output instead.

go deeper

for a junior

Recall the two package names, that the SDK was renamed from the Claude Code SDK, and that query() streams typed messages ending in a result message.

for a middle

Explain that the SDK drives a bundled Claude Code binary, so built-in tools, permissions, hooks and .claude/ configuration come with it, and contrast query() with Python's ClaudeSDKClient.

for a senior

Justify the library-or-CLI choice by where decisions must live: runtime approvals, in-process tools and hook logic argue for the SDK; a fixed allowlist in a shell job argues for claude -p.

for a principal

Weigh operating a library inside your own service, with its binary, credentials and upgrades tied to your release cycle, against running a CLI job the platform team can version and sandbox separately.

## What the Agent SDK is The **Claude Agent SDK** is Claude Code packaged as a library. An *agent* here means a program that completes a task by planning its own steps and calling tools that read files, run commands or edit code. The SDK gives Python and TypeScript applications the same **built-in tools**, the same **agent loop** (model call, tool call, tool result, next model call) and the same context management that the Claude Code terminal uses. It is not a second implementation. Both SDKs bundle a native Claude Code binary for the platform and run it on your behalf, which is why everything that works in Claude Code is available: permission rules and modes, hooks, subagents, MCP servers, sessions, skills and `CLAUDE.md`. If the bundled binary is missing (the TypeScript optional dependency was skipped, or pip installed a Python source distribution with no platform wheel), you point the SDK at a separately installed `claude` binary. ## The packages and the rename | Language | Package today | Former name | |---|---|---| | TypeScript / JavaScript | `@anthropic-ai/claude-agent-sdk` | `@anthropic-ai/claude-code` | | Python | `claude-agent-sdk` (import `claude_agent_sdk`) | `claude-code-sdk` (import `claude_code_sdk`) | The product was renamed from the **Claude Code SDK** to reflect that it builds agents beyond coding. The rename came with breaking changes, so a migration is more than an import edit; the migration guide lists them. ## What a call looks like The entry point is **`query()`**. You pass a prompt and an options object (`ClaudeAgentOptions` in Python, a plain `options` object in TypeScript) and iterate the result as an async stream of typed messages: assistant text, tool calls, tool results, system messages and finally a **result message** carrying the outcome, cost and `session_id`. - **TypeScript:** `for await (const message of query({ prompt, options }))`. - **Python:** `async for message in query(prompt=..., options=...)`. - **Python `ClaudeSDKClient`:** a client object that keeps one session across several `client.query()` calls and supports interrupts; the TypeScript SDK has no such object and uses `continue: true` or `resume` on later `query()` calls instead. Authentication is an API key in `ANTHROPIC_API_KEY` (or a cloud-provider configuration). The SDK does not read `.env` files on its own, and third-party products built on it may not offer claude.ai login unless Anthropic has approved it. ## Library or CLI: how to choose | You need | Reach for | |---|---| | A nightly shell job, a Makefile step, any language other than Python or TypeScript | `claude -p` with `--output-format json` | | An approval decision made by your code or your users at runtime | SDK `canUseTool` callback | | Policy code that inspects or rewrites every tool call in-process | SDK hook callbacks | | Your own functions exposed as tools without running a separate server | SDK `tool()` plus `createSdkMcpServer` | | Multi-turn conversations, resume and fork driven by application state | SDK sessions | The deciding question is **where the decisions live**. `claude -p` takes everything up front as flags and settings files, then runs to completion; nothing in your program can answer a permission prompt or inject logic mid-run except through hooks configured on disk. The SDK keeps your process in the loop, so permission decisions, hook logic and custom tools are ordinary functions in your codebase, with types, tests and access to your application's state. ## A worked choice Suppose a team builds an internal **pull-request summary service**: a web handler receives a PR number, checks out the branch, asks the agent to read the diff and write release-note bullets, and stores the result. 1. The service is already written in TypeScript, so the SDK fits the runtime. 2. It needs a custom `get_pr_diff` tool backed by the internal git host, which `tool()` and `createSdkMcpServer` provide in-process. 3. It must refuse any write or `git push`, which is a permission and hook concern the SDK lets the service decide in code. 4. It records `session_id` from the result message so a reviewer can ask a follow-up later with `resume`. The same job as a cron script with no custom tools and a fixed tool allowlist would be simpler as `claude -p`. ## Misunderstandings to avoid - The SDK is not a thin wrapper over the Messages API; it ships the built-in tools and the permission system. - Choosing the SDK does not lose `CLAUDE.md`, skills or project hooks: by default `query()` loads the same filesystem settings as the CLI. - Python is a first-class SDK, not a shell-out wrapper around TypeScript. - The raw tool loop on the Messages API, where you execute `tool_use` blocks yourself, is a different and lower-level route that you would only take if you wanted none of Claude Code's harness.

  • Does a host running the Claude Agent SDK need Claude Code installed separately?
    Usually not. Both SDKs bundle a native Claude Code binary: TypeScript as a platform optional dependency such as `@anthropic-ai/claude-agent-sdk-darwin-arm64`, Python inside platform wheels. If the package manager skipped optional dependencies, TypeScript throws `Native CLI binary for <platform>-<arch> not found` and you set `pathToClaudeCodeExecutable`. A Python source install without a wheel finds a natively installed `claude` on `PATH`.
  • In the Python SDK, when do you use ClaudeSDKClient rather than query()?
    `query()` starts a new session per call by default and suits one-off tasks; it does not support interrupts, and continuing needs `continue_conversation` or `resume`. `ClaudeSDKClient` keeps one session across several `client.query()` calls, supports interrupts and suits chat-style applications where the next prompt depends on the last answer. TypeScript has no client object; it uses `continue: true` or `resume`.
  • Can a product built on the Agent SDK let its users sign in with their claude.ai subscription?
    Not by default. The overview states 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. Such products authenticate with an API key, `ANTHROPIC_API_KEY`, or a cloud-provider configuration.

  • The Agent SDK is a thin Messages API wrapper with no built-in tools.
  • New projects should still install claude-code-sdk; the new name is cosmetic.
  • Only TypeScript has an Agent SDK, so Python services must shell out to claude -p.
  • Embedding the SDK means losing CLAUDE.md, skills and project hooks.
  • Any product built on the SDK may offer claude.ai login to its users.
open as a page

In a Claude Agent SDK service, why does the canUseTool callback never see some tool calls, and where must a check that sees every call live?

level: seniorimportance: must knowfreq 10%

basics

~20 s

canUseTool is the last step of the SDK's permission flow, so calls already approved by a hook, a mode such as acceptEdits or bypassPermissions, or an allow rule never reach it. A check for every call belongs in a PreToolUse hook callback.

open as a page

How do you give a Claude Agent SDK agent an in-process custom tool with tool() and createSdkMcpServer, and which name do you pre-approve?

level: middleimportance: should knowfreq 8%

basics

~10 s

Define the tool with tool() (Python @tool) as name, description, schema and async handler, wrap it with createSdkMcpServer, pass it under a key in mcpServers, and pre-approve mcp__<key>__<tool> in allowedTools.

open as a page

In the Claude Agent SDK, how does a PreToolUse hook callback block or rewrite a tool call, and what silently stops it working?

level: seniorimportance: should knowfreq 6%

basics

~20 s

Register the callback under options.hooks.PreToolUse with a matcher on the tool name. Return hookSpecificOutput with permissionDecision deny and a reason to block, or updatedInput to rewrite; return an empty object to let the call proceed.

open as a page

After migrating from claude-code-sdk to the Claude Agent SDK, which defaults changed, and how do you restore Claude Code's behaviour?

level: middleimportance: nice to knowfreq 5%

basics

~20 s

Since Agent SDK v0.1.0 the packages and Python's ClaudeCodeOptions are renamed, and query() uses a minimal system prompt instead of Claude Code's; request the claude_code preset to restore it. Filesystem settings still load by default.

open as a page

A Claude Agent SDK service on a shared host picks up a developer's CLAUDE.md, hooks and allow rules; why, and how do you isolate it?

level: seniorimportance: nice to knowfreq 4%

basics

~20 s

Omitting settingSources loads user, project and local settings, CLAUDE.md, skills and hooks, exactly like the CLI. Pass settingSources: [], then switch off auto memory and claude.ai connectors separately; managed policy and ~/.claude.json are still read.

open as a page