skip to content

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.