Agent SDK reference - TypeScript

Installation

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> 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. 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> 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:

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.

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

Parameters

Parameter	Type	Description
`prompt`	`string \| AsyncIterable<SDKUserMessage>`	The input prompt as a string or async iterable for streaming mode
`options`	`Options`	Optional configuration object (see Options type below)

Returns

Returns a Query object that extends AsyncGenerator<SDKMessage, void> with additional methods.

`startup()`

Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available. The returned WarmQuery handle accepts a prompt later and writes it to an already-ready process, so the first query() call resolves without paying subprocess spawn and initialization cost inline.

function startup(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<WarmQuery>;

Parameters

Parameter	Type	Description
`options`	`Options`	Optional configuration object. Same as the `options` parameter to `query()`
`initializeTimeoutMs`	`number`	Maximum time in milliseconds to wait for subprocess initialization. Defaults to `60000`. If initialization does not complete in time, the promise rejects with a timeout error

Returns

Returns a Promise<WarmQuery> that resolves once the subprocess has spawned and completed its initialize handshake.

Example

Call startup() early, for example on application boot, then call .query() on the returned handle once a prompt is ready. This moves subprocess spawn and initialization out of the critical path.

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

// Pay startup cost upfront
const warm = await startup({ options: { maxTurns: 3 } });

// Later, when a prompt is ready, this is immediate
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

`tool()`

Creates a type-safe MCP tool definition for use with SDK MCP servers.

function tool<Schema extends AnyZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
  extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }
): SdkMcpToolDefinition<Schema>;

Parameters

Parameter	Type	Description
`name`	`string`	The name of the tool
`description`	`string`	A description of what the tool does
`inputSchema`	`Schema extends AnyZodRawShape`	Zod schema defining the tool’s input parameters (supports both Zod 3 and Zod 4)
`handler`	`(args, extra) => Promise<CallToolResult>`	Async function that executes the tool logic
`extras`	`{ annotations?:` `ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }`	Optional extras. `annotations` provides MCP behavioral hints to clients. `searchHint` is a one-line capability phrase shown in the deferred-tool list when tool search is active. `alwaysLoad: true` keeps this tool’s full schema in the initial prompt instead of deferring it

`ToolAnnotations`

Re-exported from @modelcontextprotocol/sdk/types.js. All fields are optional hints; clients should not rely on them for security decisions.

Field	Type	Default	Description
`title`	`string`	`undefined`	Human-readable title for the tool
`readOnlyHint`	`boolean`	`false`	If `true`, the tool does not modify its environment
`destructiveHint`	`boolean`	`true`	If `true`, the tool may perform destructive updates (only meaningful when `readOnlyHint` is `false`)
`idempotentHint`	`boolean`	`false`	If `true`, repeated calls with the same arguments have no additional effect (only meaningful when `readOnlyHint` is `false`)
`openWorldHint`	`boolean`	`true`	If `true`, the tool interacts with external entities (for example, web search). If `false`, the tool’s domain is closed (for example, a memory tool)

import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const searchTool = tool(
  "search",
  "Search the web",
  { query: z.string() },
  async ({ query }) => {
    return { content: [{ type: "text", text: `Results for: ${query}` }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } }
);

`createSdkMcpServer()`

Creates an MCP server instance that runs in the same process as your application.

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

Agent SDK reference - TypeScript

Installation

Compile to a single executable

Functions

`query()`

Parameters

Returns

`startup()`

Parameters

Returns

Example

`tool()`

Parameters

`ToolAnnotations`

`createSdkMcpServer()`

​Installation

​Compile to a single executable

​Functions

​query()

​Parameters

​Returns

​startup()

​Parameters

​Returns

​Example

​tool()

​Parameters

​ToolAnnotations

​createSdkMcpServer()

Installation

Compile to a single executable

Functions

`query()`

Parameters

Returns

`startup()`

Parameters

Returns

Example

`tool()`

Parameters

`ToolAnnotations`

`createSdkMcpServer()`