AI 原生开放教材

外观

claude-code-docs-official官方文档·英文原文 ↗原件 ↓仓库 ↗

Agent SDK reference - TypeScript ​

Complete API reference for the TypeScript Agent SDK, including all functions, types, and interfaces.

<script defer />

Installation ​

bash
npm install @anthropic-ai/claude-agent-sdk

The SDK bundles a native Claude Code binary for your platform as an optional dependency such as @anthropic-ai/claude-agent-sdk-darwin-arm64. Most installs need no separate Claude Code install. The SDK version tracks the bundled Claude Code version. SDK v0.3.191 bundles Claude Code v2.1.191, so a feature on this page that requires a Claude Code version needs the SDK release with the same patch number or later. If your package manager skips optional dependencies, the SDK throws Native CLI binary for <platform>-<arch> not found; set pathToClaudeCodeExecutable to a separately installed claude binary instead.

If your package manager doesn't apply npm's libc field, as Yarn 1.x doesn't, you get both the glibc and musl platform packages on Linux, roughly doubling the install size. On Agent SDK v0.2.141 or later, the SDK still launches the correct variant. To reclaim the space in a container image, delete the platform package that doesn't match the libc where your app runs; for a glibc runtime on x64, that's rm -rf node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl. On a development machine the deletion is temporary, since Yarn reinstalls the package on the next dependency change.

Compile to a single executable ​

When you compile your application into a single-file executable with bun build --compile, the SDK cannot resolve the bundled CLI binary at runtime. require.resolve does not work inside the compiled executable's $bunfs virtual filesystem, so the SDK throws Native CLI binary for <platform>-<arch> not found.

To work around this, embed the platform binary as a file asset, extract it to a real path at startup with extractFromBunfs(), and pass that path to pathToClaudeCodeExecutable.

The extractFromBunfs() helper requires @anthropic-ai/claude-agent-sdk v0.3.144 or later. The example below builds for macOS on Apple Silicon:

typescript
import binPath from "@anthropic-ai/claude-agent-sdk-darwin-arm64/claude" with { type: "file" };
import { extractFromBunfs } from "@anthropic-ai/claude-agent-sdk/extract";
import { query } from "@anthropic-ai/claude-agent-sdk";

const cliPath = extractFromBunfs(binPath);

for await (const message of query({
  prompt: "Hello",
  options: { pathToClaudeCodeExecutable: cliPath },
})) {
  console.log(message);
}

extractFromBunfs() copies the embedded binary out of the compiled executable's virtual filesystem to a per-user temp directory and returns the real path. Outside a compiled executable it returns the input path unchanged, so the same code runs in development without modification.

Each compiled executable embeds a single platform's binary. Match the platform package in the import to your --target:

  • To cross-compile, install the non-matching platform package, for example npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force.
  • On Windows, the binary subpath is claude.exe, for example @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe.

Functions ​

query() ​

The primary function for interacting with Claude Code. Creates an async generator that streams messages as they arrive.

typescript
function query({
  prompt,
  options
}: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query;

本篇目录 ​