Tham chiếu TypeScript SDK

Tham chiếu API đầy đủ cho Agent SDK bản TypeScript, gồm mọi function, type, và interface.

Chú ý

Tài liệu tham chiếu SDK có thể thay đổi thường xuyên khi các phiên bản mới ra mắt. Kiểm tra tài liệu gốc để có signature và danh sách field mới nhất trước khi dựa vào nội dung trang này.

Cài đặt

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

Ghi chú

SDK đóng gói sẵn một binary Claude Code gốc (native) cho platform của bạn như một optional dependency, ví dụ @anthropic-ai/claude-agent-sdk-darwin-arm64. Bạn không cần cài Claude Code riêng. Phiên bản SDK bám theo phiên bản Claude Code được đóng gói kèm: SDK v0.3.191 đóng gói Claude Code v2.1.191, nên một tính năng trên trang này yêu cầu một phiên bản Claude Code cụ thể thì cần bản SDK có cùng số patch trở lên. Nếu package manager của bạn bỏ qua optional dependencies, SDK sẽ throw Native CLI binary for <platform> not found; hãy đặt pathToClaudeCodeExecutable trỏ tới một binary claude cài riêng thay vào đó.

Compile thành một executable đơn file

Khi bạn compile ứng dụng thành một executable đơn file bằng bun build --compile, SDK không thể resolve binary CLI đã đóng gói lúc runtime. require.resolve không hoạt động bên trong virtual filesystem $bunfs của executable đã compile, nên SDK sẽ throw Native CLI binary for <platform> not found.

Để khắc phục, embed binary của platform như một file asset, extract nó ra một đường dẫn thật lúc startup bằng extractFromBunfs(), rồi truyền đường dẫn đó vào pathToClaudeCodeExecutable.

Helper extractFromBunfs() yêu cầu @anthropic-ai/claude-agent-sdk v0.3.144 trở lên. Ví dụ dưới đây build cho macOS trên 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() copy binary đã embed ra khỏi virtual filesystem của executable đã compile, đưa vào một thư mục temp riêng cho từng user, và trả về đường dẫn thật. Bên ngoài một executable đã compile, nó trả về nguyên đường dẫn input, nên cùng đoạn code chạy được trong môi trường dev mà không cần sửa gì.

Mỗi executable đã compile embed binary của một platform duy nhất. Khớp package platform trong import với --target của bạn:

• Để cross-compile, cài package của platform không khớp, ví dụ npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force.
• Trên Windows, subpath của binary là claude.exe, ví dụ @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe.

Functions

query()

Function chính để tương tác với Claude Code. Tạo một async generator stream message khi chúng đến.

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

Parameters

Parameter	Type	Description
prompt	string | AsyncIterable<SDKUserMessage>	Prompt đầu vào dưới dạng string hoặc async iterable cho streaming mode
options	Options	Object cấu hình tuỳ chọn (xem type Options bên dưới)

Returns

Trả về một object Query mở rộng AsyncGenerator<SDKMessage, void> với các method bổ sung.

startup()

Pre-warm (làm nóng trước) subprocess CLI bằng cách spawn nó và hoàn tất handshake initialize trước khi có prompt. Handle WarmQuery trả về nhận prompt sau đó và ghi nó vào một process đã sẵn sàng, nên lời gọi query() đầu tiên resolve mà không phải trả chi phí spawn subprocess và initialization ngay tại chỗ.

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

Parameters

Parameter	Type	Description
options	Options	Object cấu hình tuỳ chọn. Giống parameter options của query()
initializeTimeoutMs	number	Thời gian tối đa (ms) để chờ subprocess khởi tạo. Mặc định 60000. Nếu khởi tạo không xong trong thời gian đó, promise reject với lỗi timeout

Returns

Trả về một Promise<WarmQuery> resolve khi subprocess đã spawn và hoàn tất handshake initialize.

Example

Gọi startup() sớm, ví dụ lúc ứng dụng boot, rồi gọi .query() trên handle trả về khi có prompt sẵn sàng. Cách này đưa việc spawn và khởi tạo subprocess ra khỏi critical path.

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

// Trả chi phí startup trước
const warm = await startup({ options: { maxTurns: 3 } });

// Sau đó, khi prompt đã sẵn sàng, việc này diễn ra ngay lập tức
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

tool()

Tạo một định nghĩa MCP tool type-safe để dùng với SDK MCP server.

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	Tên của tool
description	string	Mô tả tool làm gì
inputSchema	Schema extends AnyZodRawShape	Zod schema định nghĩa input parameter của tool (hỗ trợ cả Zod 3 và Zod 4)
handler	(args, extra) => Promise<CallToolResult>	Hàm async thực thi logic của tool
extras	{ annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }	Extras tuỳ chọn. annotations cung cấp gợi ý hành vi MCP cho client. searchHint là một câu ngắn mô tả khả năng, hiển thị trong danh sách deferred-tool khi tool search đang bật. alwaysLoad: true giữ nguyên schema đầy đủ của tool này trong prompt ban đầu thay vì defer nó

ToolAnnotations

Re-export từ @modelcontextprotocol/sdk/types.js. Mọi field đều là gợi ý tuỳ chọn; client không nên dựa vào chúng cho quyết định bảo mật.

Field	Type	Default	Description
title	string	undefined	Tiêu đề dễ đọc cho tool
readOnlyHint	boolean	false	Nếu true, tool không thay đổi môi trường của nó
destructiveHint	boolean	true	Nếu true, tool có thể thực hiện cập nhật mang tính phá huỷ (chỉ có ý nghĩa khi readOnlyHint là false)
idempotentHint	boolean	false	Nếu true, các lời gọi lặp lại với cùng argument không có thêm tác dụng phụ (chỉ có ý nghĩa khi readOnlyHint là false)
openWorldHint	boolean	true	Nếu true, tool tương tác với thực thể bên ngoài (ví dụ, web search). Nếu false, domain của tool đóng kín (ví dụ, một 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()

Tạo một MCP server instance chạy trong cùng process với ứng dụng của bạn.

function createSdkMcpServer(options: {
  name: string;
  version?: string;
  instructions?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
  alwaysLoad?: boolean;
}): McpSdkServerConfigWithInstance;

Parameters

Parameter	Type	Description
options.name	string	Tên của MCP server
options.version	string	Chuỗi version tuỳ chọn
options.instructions	string	Instructions server tuỳ chọn, trả về từ initialize và đưa ra cho model như một khối MCP instructions
options.tools	Array<SdkMcpToolDefinition>	Mảng định nghĩa tool tạo bằng tool()
options.alwaysLoad	boolean	Khi true, mọi tool từ server này giữ nguyên trong prompt ban đầu và không bao giờ bị defer sau tool search. Kết hợp với alwaysLoad từng tool trong tool()

listSessions()

Khám phá và liệt kê các session trong quá khứ với metadata nhẹ. Lọc theo project directory hoặc liệt kê session trên mọi project.

function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

Parameters

Parameter	Type	Default	Description
options.dir	string	undefined	Thư mục để liệt kê session. Nếu bỏ qua, trả về session trên mọi project
options.limit	number	undefined	Số lượng session tối đa trả về
options.includeWorktrees	boolean	true	Khi dir nằm trong một git repository, bao gồm cả session từ mọi worktree path

Return type: SDKSessionInfo

Property	Type	Description
sessionId	string	Định danh session duy nhất (UUID)
summary	string	Tiêu đề hiển thị: title tuỳ chỉnh, summary tự sinh, hoặc prompt đầu tiên
lastModified	number	Thời điểm sửa đổi cuối, tính bằng mili giây kể từ epoch
fileSize	number | undefined	Kích thước file session (byte). Chỉ được điền cho local JSONL storage
customTitle	string | undefined	Tiêu đề session do người dùng đặt (qua /rename)
firstPrompt	string | undefined	Prompt người dùng có ý nghĩa đầu tiên trong session
gitBranch	string | undefined	Git branch tại thời điểm cuối session
cwd	string | undefined	Thư mục làm việc của session
tag	string | undefined	Tag session do người dùng đặt (xem tagSession())
createdAt	number | undefined	Thời điểm tạo (mili giây kể từ epoch), lấy từ timestamp của entry đầu tiên

Example

In ra 10 session gần nhất của một project. Kết quả sắp theo lastModified giảm dần, nên item đầu tiên là mới nhất. Bỏ qua dir để tìm trên mọi project.

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

const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });

for (const session of sessions) {
  console.log(`${session.summary} (${session.sessionId})`);
}

getSessionMessages()

Đọc message user và assistant từ một session transcript trong quá khứ.

function getSessionMessages(
  sessionId: string,
  options?: GetSessionMessagesOptions
): Promise<SessionMessage[]>;

Parameters

Parameter	Type	Default	Description
sessionId	string	required	UUID session cần đọc (xem listSessions())
options.dir	string	undefined	Project directory để tìm session. Nếu bỏ qua, tìm trên mọi project
options.limit	number	undefined	Số message tối đa trả về
options.offset	number	undefined	Số message bỏ qua tính từ đầu

Return type: SessionMessage

Property	Type	Description
type	"user" | "assistant"	Vai trò của message
uuid	string	Định danh message duy nhất
session_id	string	Session mà message này thuộc về
message	unknown	Payload message thô từ transcript
parent_tool_use_id	string | null	Với message của subagent, tool_use_id của lời gọi tool Agent đã spawn nó. null cho message main-session và session cũ
parent_agent_id	string | null	Với message từ một subagent lồng nhau, agentId của subagent đã spawn nó. null cho message main-session, message từ subagent cấp cao nhất, và session cũ. Yêu cầu Claude Code v2.1.202 trở lên

Example

import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 });

if (latest) {
  const messages = await getSessionMessages(latest.sessionId, {
    dir: "/path/to/project",
    limit: 20
  });

  for (const msg of messages) {
    console.log(`[${msg.type}] ${msg.uuid}`);
  }
}

getSessionInfo()

Đọc metadata cho một session đơn lẻ theo ID mà không quét toàn bộ project directory.

function getSessionInfo(
  sessionId: string,
  options?: GetSessionInfoOptions
): Promise<SDKSessionInfo | undefined>;

Parameters

Parameter	Type	Default	Description
sessionId	string	required	UUID của session cần tra cứu
options.dir	string	undefined	Đường dẫn project directory. Nếu bỏ qua, tìm trên mọi project directory

Trả về SDKSessionInfo, hoặc undefined nếu không tìm thấy session.

renameSession()

Đổi tên một session bằng cách thêm một entry custom-title. Gọi lặp lại vẫn an toàn; title gần nhất thắng.

function renameSession(
  sessionId: string,
  title: string,
  options?: SessionMutationOptions
): Promise<void>;

Parameters

Parameter	Type	Default	Description
sessionId	string	required	UUID của session cần đổi tên
title	string	required	Tiêu đề mới. Phải khác rỗng sau khi trim khoảng trắng
options.dir	string	undefined	Đường dẫn project directory. Nếu bỏ qua, tìm trên mọi project directory

tagSession()

Gắn tag cho một session. Truyền null để xoá tag. Gọi lặp lại vẫn an toàn; tag gần nhất thắng.

function tagSession(
  sessionId: string,
  tag: string | null,
  options?: SessionMutationOptions
): Promise<void>;

Parameters

Parameter	Type	Default	Description
sessionId	string	required	UUID của session cần gắn tag
tag	string | null	required	Chuỗi tag, hoặc null để xoá
options.dir	string	undefined	Đường dẫn project directory. Nếu bỏ qua, tìm trên mọi project directory

resolveSettings()

Resolve settings Claude Code hiệu lực cho một thư mục cho trước, dùng cùng merge engine với CLI, mà không spawn Claude CLI. Dùng nó để kiểm tra cấu hình mà một lời gọi query() sẽ thấy trước khi thực sự gọi.

Ghi chú

Function này ở giai đoạn alpha và API có thể thay đổi trước khi ổn định. Nó đọc các nguồn MDM, gồm macOS plist và Windows HKLM/HKCU, để tương đương với CLI startup, nhưng không thực thi subprocess policyHelper do admin cấu hình. Field permissions.defaultMode được trả về nguyên trạng từ mọi tier kể cả project settings. Bộ lọc trust mà CLI áp dụng trước khi tôn trọng các permission mode leo thang không được áp dụng ở đây.

function resolveSettings(
  options?: ResolveSettingsOptions
): Promise<ResolvedSettings>;

Parameters

resolveSettings() nhận một object options duy nhất. Mọi field đều tuỳ chọn.

Parameter	Type	Default	Description
options.cwd	string	process.cwd()	Thư mục để resolve project và local settings tương đối theo
options.settingSources	SettingSource[]	Mọi nguồn	Nguồn filesystem nào sẽ load. Truyền [] để bỏ qua user, project, và local settings. Policy do endpoint quản lý luôn load. Server-managed settings lấy từ serverManagedSettings khi host truyền vào, hoặc đọc từ cache trên đĩa của CLI nếu không; snapshot không fetch chúng qua mạng
options.managedSettings	Settings	undefined	Settings tầng policy do host embedding cung cấp. Theo cùng quy tắc với managedSettings trong Options, ngoại trừ việc resolveSettings() không thực thi policyHelper đã cấu hình, nên snapshot có thể chứa settings mà một live session sẽ loại bỏ
options.serverManagedSettings	Settings	undefined	Payload server-managed settings từ /api/claude_code/settings. Các key không mang tính hạn chế được truyền qua không lọc

Return type: ResolvedSettings

resolveSettings() trả về một object mô tả settings đã merge và nguồn đóng góp cho từng key.

Property	Type	Description
effective	Settings	Settings đã merge sau khi áp dụng mọi nguồn được bật theo thứ tự ưu tiên
provenance	Partial<Record<keyof Settings, ProvenanceEntry>>	Với mỗi key top-level trong effective, nguồn nào đã cung cấp giá trị đó
sources	Array<{ source, settings, path?, policyOrigin? }>	Settings thô theo từng nguồn, sắp từ ưu tiên thấp nhất đến cao nhất

Example

Ví dụ dưới đây resolve settings cho một project directory và in ra nguồn kiểm soát cleanup period. Trên máy không có settings file nào đặt cleanupPeriodDays, cả hai dòng in ra đều hiện undefined cho giá trị - đó là kết quả mong đợi chứ không phải lỗi.

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

const { effective, provenance } = await resolveSettings({
  cwd: "/path/to/project",
  settingSources: ["user", "project", "local"],
});

console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);
console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);

Types

Options

Object cấu hình cho function query().

Property	Type	Default	Description
abortController	AbortController	new AbortController()	Controller để huỷ hoạt động
additionalDirectories	string[]	[]	Thư mục bổ sung Claude có thể truy cập
agent	string	undefined	Tên agent cho main thread. Agent phải được định nghĩa trong option agents hoặc trong settings
agents	Record<string, [AgentDefinition](#agentdefinition)>	undefined	Định nghĩa subagent bằng code
agentProgressSummaries	boolean	false	Khi true, sinh tóm tắt tiến độ một dòng cho subagent và forward qua event task_progress ở field summary. Áp dụng cho cả subagent foreground và background
allowDangerouslySkipPermissions	boolean	false	Cho phép bỏ qua permission. Cần thiết khi dùng permissionMode: 'bypassPermissions'
allowedTools	string[]	[]	Tool tự động chấp thuận không cần hỏi. Không giới hạn Claude chỉ dùng những tool này; tool không nằm trong danh sách sẽ rơi xuống permissionMode và canUseTool. Dùng disallowedTools để chặn tool. Xem Permissions
betas	SdkBeta[]	[]	Bật tính năng beta
canUseTool	CanUseTool	undefined	Function permission tuỳ chỉnh, chỉ được gọi khi luồng permission rơi xuống một prompt. Không được gọi cho lời gọi đã tự động chấp thuận bởi allowedTools, allow rule, hoặc permissionMode. AskUserQuestion, connector tool tổ chức của bạn đặt là ask, và MCP tool đánh dấu requiresUserInteraction vẫn tới được nó dù bạn đã allow chúng; ở mode dontAsk các trường hợp này bị deny thay vào đó. Xem CanUseTool để biết chi tiết
continue	boolean	false	Tiếp tục hội thoại gần nhất
cwd	string	process.cwd()	Thư mục làm việc hiện tại
debug	boolean	false	Bật debug mode cho process Claude Code
debugFile	string	undefined	Ghi debug log vào một file path cụ thể. Ngầm định bật debug mode
disallowedTools	string[]	[]	Tool cần deny. Tên trần như "Bash" loại tool khỏi context của Claude. Một rule có scope như "Bash(rm *)" vẫn để tool khả dụng nhưng deny lời gọi khớp ở mọi permission mode, kể cả bypassPermissions. Xem Permissions
effort	'low' | 'medium' | 'high' | 'xhigh' | 'max'	Mặc định của model	Kiểm soát mức độ Claude đầu tư vào phản hồi. Kết hợp với adaptive thinking để định hướng độ sâu suy nghĩ. Xem điều chỉnh effort level
enableFileCheckpointing	boolean	false	Bật theo dõi thay đổi file để rewind. Xem File checkpointing
env	Record<string, string | undefined>	process.env	Biến môi trường. Khi đặt, giá trị này thay thế toàn bộ môi trường subprocess thay vì merge với process.env, nên hãy truyền { ...process.env, YOUR_VAR: 'value' } để giữ các biến thừa kế như PATH. Xem Handle slow or stalled API responses để có ví dụ về pattern này, và Environment variables cho các biến CLI bên dưới đọc. Đặt CLAUDE_AGENT_SDK_CLIENT_APP để định danh app của bạn trong header User-Agent
executable	'bun' | 'deno' | 'node'	Tự động phát hiện	JavaScript runtime để dùng
executableArgs	string[]	[]	Argument truyền cho executable
extraArgs	Record<string, string | null>	{}	Argument bổ sung
fallbackModel	string	undefined	Model dùng nếu model chính lỗi
forkSession	boolean	false	Khi resume bằng resume, fork sang một session ID mới thay vì tiếp tục session gốc
forwardSubagentText	boolean	false	Forward text và thinking block của subagent như message assistant và user có set parent_tool_use_id, để consumer render một transcript lồng nhau. Mặc định chỉ khối tool_use và tool_result từ subagent được emit. Message từ subagent ở mọi độ sâu lồng nhau được forward trên Claude Code v2.1.219 trở lên; trước v2.1.219, chỉ message từ subagent độ sâu 1 xuất hiện
hooks	Partial<Record<HookEvent, HookCallbackMatcher[]>>	{}	Hook callback cho các event
includeHookEvents	boolean	false	Bao gồm hook lifecycle event cho mọi hook event trong message stream, dưới dạng SDKHookStartedMessage, SDKHookProgressMessage, và SDKHookResponseMessage. Lifecycle event cho hook SessionStart và Setup luôn được bao gồm, không cần option này
includePartialMessages	boolean	false	Bao gồm partial message event
loadTimeoutMs	number	60000	Alpha. Timeout (ms) cho mỗi lời gọi sessionStore.load() và sessionStore.listSubkeys() trong lúc materialize resume. Nếu adapter không settle trong khoảng này, query sẽ fail thay vì treo. Bỏ qua khi không đặt sessionStore
managedSettings	Settings	undefined	Settings tầng policy mà host process của bạn cung cấp cho session được spawn. Trên máy có managed settings do admin deploy, Claude Code bỏ qua các giá trị này trừ khi nguồn managed ưu tiên cao nhất của admin đặt parentSettingsBehavior: 'merge', và không bao giờ merge khi có policyHelper được cấu hình. Giá trị đã merge đi qua bộ lọc chỉ-hạn-chế; Restrict parent settings mô tả những gì bộ lọc chấp nhận và các khoá allowManaged*Only
maxBudgetUsd	number	undefined	Dừng query khi ước tính chi phí phía client đạt giá trị USD này. So sánh với cùng ước tính như total_cost_usd; xem Track cost and usage để biết các lưu ý về độ chính xác
maxThinkingTokens	number	undefined	Deprecated: Dùng thinking thay thế. Số token tối đa cho quá trình thinking
maxTurns	number	undefined	Số turn agentic tối đa (vòng lặp tool-use)
mcpServers	Record<string, [McpServerConfig](#mcpserverconfig)>	{}	Cấu hình MCP server
model	string	Mặc định từ CLI	Alias model Claude hoặc tên model đầy đủ. Xem giá trị chấp nhận và ID theo provider
onElicitation	(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>	undefined	Callback xử lý MCP elicitation request. Gọi khi một MCP server yêu cầu input từ người dùng và không có hook nào xử lý trước. Khi không cung cấp, elicitation request không xử lý bị decline tự động
outputFormat	{ type: 'json_schema', schema: JSONSchema }	undefined	Định nghĩa format output cho kết quả agent. Xem Structured outputs để biết chi tiết
outputStyle	string	undefined	Không phải field của Options. Đặt outputStyle trong object settings inline hoặc trong settings file thay vào đó. Xem Activate an output style
pathToClaudeCodeExecutable	string	Tự động resolve từ binary native đóng gói	Đường dẫn tới Claude Code executable. Chỉ cần khi optional dependency bị bỏ qua lúc cài đặt hoặc platform của bạn không nằm trong danh sách hỗ trợ
permissionMode	PermissionMode	'default'	Permission mode cho session
permissionPromptToolName	string	undefined	Tên MCP tool cho permission prompt
persistSession	boolean	true	Khi false, tắt lưu session xuống đĩa. Session không thể resume sau này
planModeInstructions	string	undefined	Instructions workflow tuỳ chỉnh cho plan mode. Khi permissionMode là 'plan', chuỗi này thay thế nội dung workflow plan-mode mặc định. CLI vẫn bọc nó với preamble read-only enforcement và footer protocol ExitPlanMode
plugins	SdkPluginConfig[]	[]	Load plugin tuỳ chỉnh từ đường dẫn local. Xem Plugins để biết chi tiết
promptSuggestions	boolean	false	Bật gợi ý prompt. Emit một message prompt_suggestion sau mỗi turn với dự đoán prompt kế tiếp của người dùng
resume	string	undefined	Session ID để resume
resumeSessionAt	string	undefined	Resume session tại một message UUID cụ thể
sandbox	SandboxSettings	undefined	Cấu hình hành vi sandbox bằng code. Xem Sandbox settings để biết chi tiết
sessionId	string	Tự động sinh	Dùng một UUID cụ thể cho session thay vì tự sinh
sessionStore	SessionStore	undefined	Mirror session transcript vào một backend ngoài để bất kỳ host nào cũng resume được. Xem Persist sessions to external storage
sessionStoreFlush	'batched' | 'eager'	'batched'	Alpha. Flush mode cho sessionStore. Bỏ qua khi không đặt sessionStore
settings	string | Settings	undefined	Object settings inline hoặc đường dẫn tới settings file. Điền vào tầng flag-settings trong thứ tự ưu tiên. Đổi lúc runtime bằng applyFlagSettings()
settingSources	SettingSource[]	Mặc định CLI (mọi nguồn)	Kiểm soát settings filesystem nào được load. Truyền [] để tắt user, project, và local settings. Policy do endpoint quản lý luôn load; server-managed settings được fetch khi session xác thực bằng credential tổ chức trên cấu hình đủ điều kiện. Xem Use Claude Code features
skills	string[] | 'all'	undefined	Skill khả dụng cho session. Truyền 'all' để bật mọi skill phát hiện được, hoặc một danh sách tên skill. Khi đặt, SDK tự thêm Skill tool vào allowedTools. Nếu bạn cũng truyền tools, hãy bao gồm 'Skill' trong danh sách đó. Xem Skills
spawnClaudeCodeProcess	(options: SpawnOptions) => SpawnedProcess	undefined	Function spawn tuỳ chỉnh cho process Claude Code. Dùng để chạy Claude Code trong VM, container, hoặc môi trường remote
stderr	(data: string) => void	undefined	Callback cho output stderr
strictMcpConfig	boolean	false	Chỉ dùng server truyền trong mcpServers, bỏ qua .mcp.json của project, user settings, MCP server do plugin cung cấp, và claude.ai connector
systemPrompt	string | { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }	undefined (prompt tối giản)	Cấu hình system prompt. Truyền một string cho prompt tuỳ chỉnh, hoặc { type: 'preset', preset: 'claude_code' } để dùng system prompt của Claude Code. Khi dùng dạng object preset, thêm append để mở rộng nó với instruction bổ sung, và đặt excludeDynamicSections: true để chuyển context theo từng session vào message user đầu tiên nhằm tái sử dụng prompt-cache tốt hơn giữa các máy
taskBudget	{ total: number }	undefined	Alpha. Task budget phía API tính bằng token. Khi đặt, model được báo ngân sách token còn lại để tự điều tiết dùng tool và kết thúc trước khi hết giới hạn
thinking	ThinkingConfig	{ type: 'adaptive' } cho model hỗ trợ	Kiểm soát hành vi thinking/reasoning của Claude. Xem ThinkingConfig để biết tuỳ chọn
title	string	undefined	Tiêu đề hiển thị cho session. Khi resume qua resume hoặc continue, title đã lưu của session được resume được ưu tiên; dùng renameSession() để đổi tên một session có sẵn
toolAliases	Record<string, string>	undefined	Map tên built-in tool sang tên MCP tool để Claude gọi implementation MCP của bạn thay cho built-in. Ví dụ, { Bash: 'mcp__workspace__bash' }
toolConfig	ToolConfig	undefined	Cấu hình hành vi built-in tool. Xem ToolConfig để biết chi tiết
tools	string[] | { type: 'preset'; preset: 'claude_code' }	undefined	Cấu hình tool. Truyền một mảng tên tool hoặc dùng preset để lấy bộ tool mặc định của Claude Code

Handle slow or stalled API responses

Subprocess CLI đọc một số biến môi trường kiểm soát API timeout và phát hiện stall (treo). Truyền chúng qua option env:

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

const result = query({
  prompt: "Analyze this code",
  options: {
    env: {
      ...process.env,
      API_TIMEOUT_MS: "120000",
      CLAUDE_CODE_MAX_RETRIES: "2",
      CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000",
    },
  },
});

• API_TIMEOUT_MS: timeout cho mỗi request trên Anthropic client, tính bằng mili giây. Mặc định 600000. Áp dụng cho main loop và mọi subagent.
• CLAUDE_CODE_MAX_RETRIES: số lần retry API tối đa. Mặc định 10, giới hạn tối đa 15. Mỗi lần retry có cửa sổ API_TIMEOUT_MS riêng, nên thời gian chờ tệ nhất xấp xỉ API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) cộng thêm backoff. Với các lần chạy không giám sát cần chờ qua các đợt outage dài hơn, đặt CLAUDE_CODE_RETRY_WATCHDOG=1: nó retry lỗi capacity vô hạn định, và kể từ Claude Code v2.1.199, nâng mặc định cho các lỗi tạm thời khác lên 300 và bỏ giới hạn trên biến này.
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: watchdog stall cho subagent chạy với run_in_background. Mặc định 600000. Reset mỗi khi có stream event; khi stall nó abort subagent, đánh dấu task fail, và báo lỗi cho parent kèm kết quả một phần (nếu có). Không áp dụng cho subagent đồng bộ.
• CLAUDE_ENABLE_STREAM_WATCHDOG cùng CLAUDE_STREAM_IDLE_TIMEOUT_MS: abort request khi header đã tới nhưng response body ngừng stream. Watchdog bật mặc định cho mọi provider; đặt CLAUDE_ENABLE_STREAM_WATCHDOG=0 để tắt. CLAUDE_STREAM_IDLE_TIMEOUT_MS mặc định 300000 và bị clamp về mức tối thiểu đó. Sau khi abort, Claude Code retry request nhiều nhất một lần, và chỉ trước khi Claude bắt đầu một khối text hoặc tool call trong response; một khi Claude đã hoàn tất một khối text hoặc tool call, Claude Code giữ output đã hoàn tất, thêm một thông báo response-có-thể-không-đầy-đủ thay vì retry, và vẫn chạy mọi tool call đã hoàn tất.

Query object

Interface trả về bởi function query().

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<SDKControlInterruptResponse | undefined>;
  rewindFiles(
    userMessageId: string,
    options?: { dryRun?: boolean }
  ): Promise<RewindFilesResult>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  reinitialize(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  getContextUsage(): Promise<SDKControlGetContextUsageResponse>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

Methods

Method	Description
interrupt()	Ngắt query. Chỉ khả dụng ở streaming input mode. Khi CLI khai báo capability interrupt_receipt_v1 trong SDKSystemMessage.capabilities, resolve với một SDKControlInterruptResponse liệt kê message đang chờ còn sống sót sau interrupt. Resolve undefined trên các CLI trước v2.1.205
rewindFiles(userMessageId, options?)	Khôi phục file về trạng thái tại message user đã chỉ định. Truyền { dryRun: true } để xem trước thay đổi. Yêu cầu enableFileCheckpointing: true. Xem File checkpointing
setPermissionMode()	Đổi permission mode (chỉ khả dụng ở streaming input mode)
setModel()	Đổi model (chỉ khả dụng ở streaming input mode). Truyền undefined hoặc chuỗi "default" sẽ reset về model mặc định của session
setMaxThinkingTokens()	Deprecated: Dùng option thinking thay thế. Đổi số token thinking tối đa. Truyền null reset thinking về mặc định session: một override giữa chừng bị xoá, và thinking vẫn tắt với session đã disable nó
applyFlagSettings(settings)	Merge settings vào tầng flag settings của session lúc runtime (chỉ khả dụng ở streaming input mode). Xem applyFlagSettings()
initializationResult()	Trả về toàn bộ kết quả khởi tạo gồm command hỗ trợ, model, thông tin account, và cấu hình output style
reinitialize()	Gửi lại control request initialize tới CLI đang chạy và trả về kết quả mới thay vì kết quả cache từ lần connect đầu. Dùng nó sau một khoảng gián đoạn transport, ví dụ reattach một session sau khi mất kết nối, để permission request đang chờ chạm lại callback canUseTool của bạn. Làm callback idempotent theo request ID, vì một request bị mất response sẽ được dispatch lại. Yêu cầu Claude Code v2.1.195 trở lên
supportedCommands()	Trả về danh sách slash command khả dụng. Từ Agent SDK v0.3.216, danh sách phản ánh thay đổi command giữa session; xem SDKCommandsChangedMessage
supportedModels()	Trả về danh sách model khả dụng kèm thông tin hiển thị
supportedAgents()	Trả về subagent khả dụng dưới dạng AgentInfo[]
mcpServerStatus()	Trả về trạng thái các MCP server đã kết nối
getContextUsage()	Trả về một SDKControlGetContextUsageResponse phân tách usage context window của session theo category, skill, và tool. Cùng dữ liệu mà /context hiển thị trong một session tương tác
accountInfo()	Trả về thông tin account
reconnectMcpServer(serverName)	Kết nối lại một MCP server theo tên
toggleMcpServer(serverName, enabled)	Bật hoặc tắt một MCP server theo tên
setMcpServers(servers)	Thay thế động tập hợp MCP server cho session này. Trả về server nào được thêm và bỏ, cùng mọi lỗi. Lời gọi giữ nguyên server do plugin cung cấp không được nêu tên; nêu tên một server sẽ thay thế nó. Promise resolve sau khi server stdio, HTTP, và SSE mới thêm kết nối hoặc lỗi, nên tool từ server đã kết nối khả dụng ở turn kế tiếp (yêu cầu Claude Code v2.1.210 trở lên).
streamInput(stream)	Stream input message vào query cho hội thoại nhiều turn
stopTask(taskId)	Dừng một background task đang chạy theo ID
close()	Đóng query và kết thúc process bên dưới. Kết thúc query một cách cưỡng bức và dọn dẹp mọi resource

applyFlagSettings()

Đổi settings trên một session đang chạy mà không cần restart query. Dùng nó khi một setting không có setter riêng cần đổi giữa session, ví dụ siết chặt permissions sau khi agent đọc input không tin cậy. setModel() và setPermissionMode() là setter chuyên biệt cho hai key đó; applyFlagSettings() là dạng tổng quát chấp nhận bất kỳ tập con nào của các key settings, và truyền model ở đây có hành vi giống setModel().

Chỉ một số key có tác dụng giữa session:

• Áp dụng ở turn kế tiếp: effortLevel, ultracode, permissions, hooks, skillOverrides, fastMode, agent. Chuyển agent cũng áp dụng model override, hooks, và system prompt của agent đó ở turn kế tiếp.
• Áp dụng ngay trong turn hiện tại: model. Nếu bạn đổi model trong khi Claude đang xử lý một turn (từ v2.1.212), phản hồi Claude đang sinh dở sẽ hoàn tất trên model cũ, và phần còn lại của turn, bắt đầu từ lời gọi kế tiếp Claude Code gọi tới model, dùng model mới. Subagent giữ nguyên model riêng của chúng. Trước v2.1.212, một lần đổi giữa turn sẽ chờ tới turn kế tiếp.
• Không tác dụng giữa session: các option system prompt. Chúng được resolve một lần lúc startup, nên session đang chạy giữ nguyên giá trị gốc dù lời gọi thành công. Để đổi chúng, khởi động một session mới.

effortLevel chấp nhận tên một effort level. Nó cũng chấp nhận "ultracode", chạy session ở effort xhigh và bật ultracode. Type Settings khai báo effortLevel không có giá trị đó, nên hãy truyền { ultracode: true } tương đương trong TypeScript. Giá trị ultracode yêu cầu Claude Code v2.1.203 trở lên và chỉ được chấp nhận bởi applyFlagSettings(), không phải bởi key effortLevel trong settings file.

Các giá trị được ghi vào tầng flag-settings, cùng tầng mà option settings inline của query() điền vào lúc startup. Flag settings nằm gần đỉnh của thứ tự ưu tiên settings: chúng override user, project, và local settings, và chỉ managed policy settings mới override được chúng. Đây cùng tầng mà phần thứ tự ưu tiên trên trang này gọi là programmatic options.

Các lời gọi liên tiếp shallow-merge key ở cấp cao nhất. Lời gọi thứ hai với { permissions: {...} } thay thế toàn bộ object permissions từ lời gọi trước thay vì deep-merge vào nó. Để xoá một key khỏi tầng flag và quay về nguồn ưu tiên thấp hơn, truyền null cho key đó. Truyền undefined không có tác dụng vì JSON serialization bỏ nó.

Chỉ khả dụng ở streaming input mode, cùng ràng buộc với setModel() và setPermissionMode().

Ví dụ dưới đây đổi model đang dùng giữa session, sau đó xoá override để model quay về bất kỳ giá trị nào user hoặc project settings chỉ định.

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

const q = query({ prompt: messageStream });

// Override model cho phần còn lại của session
await q.applyFlagSettings({ model: "claude-opus-4-6" });

// Sau đó: xoá override và quay về settings ưu tiên thấp hơn
await q.applyFlagSettings({ model: null });

Ghi chú

applyFlagSettings() chỉ có ở TypeScript. Python SDK không có method tương đương.

WarmQuery

Handle trả về bởi startup(). Subprocess đã spawn và khởi tạo sẵn, nên gọi query() trên handle này ghi prompt trực tiếp vào một process đã sẵn sàng, không có độ trễ khởi động.

interface WarmQuery extends AsyncDisposable {
  query(prompt: string | AsyncIterable<SDKUserMessage>): Query;
  close(): void;
}

Methods

Method	Description
query(prompt)	Gửi một prompt tới subprocess đã pre-warm và trả về Query. Chỉ có thể gọi một lần cho mỗi WarmQuery
close()	Đóng subprocess mà không gửi prompt. Dùng nó để loại bỏ một warm query không còn cần nữa

WarmQuery implement AsyncDisposable, nên có thể dùng với await using để tự động dọn dẹp.

SDKControlInitializeResponse

Return type của initializationResult(). Chứa dữ liệu khởi tạo session.

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: "off" | "cooldown" | "on";
  fast_mode_disabled_reason?: FastModeDisabledReason;
};

Từ v2.1.219, response luôn báo cáo fast_mode_state, và khi có gì đó chặn fast mode, fast_mode_disabled_reason mang mã lý do kèm theo, nên bạn có thể giải thích trạng thái bị chặn thay vì tự suy luận lại tính khả dụng. Cả hai hành vi yêu cầu Claude Code v2.1.219 trở lên. Trước v2.1.219, response bỏ qua fast_mode_state khi fast mode không khả dụng và không bao giờ mang lý do. Với mã lý do và ý nghĩa, xem fast_mode_disabled_reason trên result message.

Khi một client gửi initialize tới một session đang chạy sẵn, control-response wrapper cũng mang một mảng pending_permission_requests tuỳ chọn. Field này nằm trên response wrapper, không phải trong payload SDKControlInitializeResponse ở trên. Mỗi entry là một message control_request đầy đủ với cùng hình dạng { type: "control_request", request_id, request } mà session stream cho permission request lúc đang chạy.

Đây là các request được phát hành trước khi client kết nối và vẫn đang chờ phản hồi. SDK đọc mảng này giúp bạn và dispatch từng entry tới callback canUseTool của bạn, cùng cơ chế redelivery mà reinitialize() kích hoạt sau một khoảng gián đoạn transport. Xử lý request ID lặp lại một cách idempotent, vì một entry có thể lặp lại một request mà callback đã nhận trước khi kết nối rớt.

SDKControlInterruptResponse

Biên nhận interrupt: giá trị mà interrupt() resolve trên một CLI khai báo capability interrupt_receipt_v1 trong SDKSystemMessage.capabilities. Yêu cầu Claude Code v2.1.205 trở lên. CLI cũ hơn trả lời interrupt với payload success rỗng, nên interrupt() resolve undefined.

type SDKControlInterruptResponse = {
  still_queued: string[];
  cancelled?: string[];
};

still_queued liệt kê UUID của message user còn sống sót sau interrupt: message vẫn trong queue, cộng với bất kỳ batch nào đã dequeue cho turn kế tiếp nhưng abort chưa với tới. Mỗi cái chạy như một turn riêng sau interrupt trừ khi bạn huỷ nó trước. Dùng biên nhận để quyết định có gửi lại gì không; gửi lại một message đã có trong danh sách sẽ tạo ra một turn trùng lặp.

Diễn giải danh sách với các lưu ý sau:

• Chỉ message được enqueue kèm UUID mới xuất hiện. Một mảng rỗng không có nghĩa là không có gì khác sẽ chạy.
• Chỉ message main-thread được liệt kê. Message gửi tới subagent nằm ngoài phạm vi.
• Danh sách có thể chứa UUID mà client của bạn chưa từng gửi, ví dụ trigger scheduled task. Bỏ qua UUID bạn không nhận ra thay vì coi đó là lỗi.

Một client điều khiển trực tiếp control protocol của CLI, thay vì qua interrupt(), có thể đặt cancel_queued: true trên control request interrupt (từ v2.1.219). Claude Code v2.1.219 trở lên khai báo hỗ trợ với capability interrupt_cancel_queued_v1 trong SDKSystemMessage.capabilities; CLI cũ hơn bỏ qua field này và để message đang chờ chạy như bình thường. Một interrupt như vậy cũng huỷ mọi message lẽ ra sẽ nằm trong still_queued: biên nhận liệt kê chúng dưới cancelled thay vào đó, still_queued rỗng, và không cái nào trong số đó chạy.

Danh sách cancelled có cùng lưu ý với still_queued. Method interrupt() không bao giờ gửi cancel_queued, nên biên nhận nó resolve không mang cancelled.

Biên nhận là một snapshot chụp tại thời điểm interrupt được xử lý, và trên một interrupt sạch nó tới trước SDKResultMessage của turn bị ngắt. Đọc biên nhận thay vì kiểm tra queue sau kết quả đó: vòng lặp bắt đầu turn kế tiếp trong queue ngay lập tức, nên queue bạn kiểm tra sau kết quả đã thay đổi rồi.

SDKControlGetContextUsageResponse

Return type của getContextUsage(). Đây là cùng payload mà lệnh /context render trong một session tương tác, nên bên cạnh số lượng token nó mang các field hiển thị như color, gridRows, và percentage mà /context dùng để vẽ lưới usage.

type SDKControlGetContextUsageResponse = {
  categories: {
    name: string;
    tokens: number;
    color: string;
    isDeferred?: boolean;
  }[];
  totalTokens: number;
  maxTokens: number;
  rawMaxTokens: number;
  percentage: number;
  gridRows: {
    color: string;
    isFilled: boolean;
    categoryName: string;
    tokens: number;
    percentage: number;
    squareFullness: number;
  }[][];
  model: string;
  memoryFiles: {
    path: string;
    type: string;
    tokens: number;
  }[];
  mcpTools: {
    name: string;
    serverName: string;
    tokens: number;
    isLoaded?: boolean;
  }[];
  deferredBuiltinTools?: {
    name: string;
    tokens: number;
    isLoaded: boolean;
  }[];
  systemTools?: {
    name: string;
    tokens: number;
  }[];
  systemPromptSections?: {
    name: string;
    tokens: number;
  }[];
  agents: {
    agentType: string;
    source: string;
    tokens: number;
  }[];
  slashCommands?: {
    totalCommands: number;
    includedCommands: number;
    tokens: number;
  };
  skills?: {
    totalSkills: number;
    includedSkills: number;
    tokens: number;
    skillFrontmatter: {
      name: string;
      source: string;
      tokens: number;
    }[];
  };
  autoCompactThreshold?: number;
  isAutoCompactEnabled: boolean;
  messageBreakdown?: {
    toolCallTokens: number;
    toolResultTokens: number;
    attachmentTokens: number;
    assistantMessageTokens: number;
    userMessageTokens: number;
    redirectedContextTokens: number;
    unattributedTokens: number;
    toolCallsByType: {
      name: string;
      callTokens: number;
      resultTokens: number;
    }[];
    attachmentsByType: {
      name: string;
      tokens: number;
    }[];
  };
  apiUsage: {
    input_tokens: number;
    output_tokens: number;
    cache_creation_input_tokens: number;
    cache_read_input_tokens: number;
  } | null;
};

Đọc token attribution từ các field dạng collection:

• categories chứa tổng theo từng category.
• mcpTools và agents gán token cho từng MCP tool và subagent riêng lẻ.
• memoryFiles liệt kê mỗi memory file đã load kèm chi phí của nó.
• skills.skillFrontmatter gán token của danh sách skill cho từng skill được bao gồm. Số đếm theo từng skill đo entry listing của skill đó đúng như Claude Code thực sự gửi, có thể ngắn hơn frontmatter đầy đủ của skill. So sánh skills.totalSkills với skills.includedSkills để biết mọi skill phát hiện được có lọt vào listing hay không.

totalTokens là usage context hiện tại của session, và maxTokens là cửa sổ mà usage đó được đo theo. Cửa sổ đó là context window của model, hoặc cửa sổ auto-compaction thấp hơn khi có áp dụng. Claude Code để trống các diagnostic tuỳ chọn deferredBuiltinTools, systemTools, và systemPromptSections, nên hãy lường trước chúng vắng mặt dù type có khai báo.

AgentDefinition

Cấu hình cho một subagent được định nghĩa bằng code.

type AgentDefinition = {
  description: string;
  tools?: string[];
  disallowedTools?: string[];
  prompt: string;
  model?: string;
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  initialPrompt?: string;
  maxTurns?: number;
  background?: boolean;
  memory?: "user" | "project" | "local";
  effort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
  permissionMode?: PermissionMode;
  criticalSystemReminder_EXPERIMENTAL?: string;
};

Field	Required	Description
description	Yes	Mô tả ngôn ngữ tự nhiên khi nào dùng agent này
tools	No	Mảng tên tool được phép. Nếu bỏ qua, kế thừa mọi tool khả dụng cho subagent. Để preload Skill vào context của agent, dùng field skills thay vì liệt kê 'Skill' ở đây
disallowedTools	No	Mảng tên tool bị cấm rõ ràng cho agent này. Pattern cấp MCP server cũng được chấp nhận: mcp__server hoặc mcp__server__* loại mọi tool của server đó, và mcp__* loại mọi MCP tool từ mọi server
prompt	Yes	System prompt của agent
model	No	Model override cho agent này. Chấp nhận alias như 'fable', 'opus', 'sonnet', 'haiku', 'inherit', hoặc một model ID đầy đủ. Nếu bỏ qua hoặc 'inherit', dùng model chính
mcpServers	No	Đặc tả MCP server cho agent này
skills	No	Mảng tên skill preload vào context của agent
initialPrompt	No	Tự động gửi làm turn user đầu tiên khi agent này chạy như main thread agent
maxTurns	No	Số turn agentic tối đa (round-trip API) trước khi dừng
background	No	Chạy agent này như một background task không-blocking khi được gọi
memory	No	Nguồn memory cho agent này: 'user', 'project', hoặc 'local'
effort	No	Mức độ reasoning effort cho agent này. Chấp nhận tên level hoặc một số nguyên
permissionMode	No	Permission mode cho việc thực thi tool trong agent này. Xem PermissionMode
criticalSystemReminder_EXPERIMENTAL	No	Thử nghiệm: reminder quan trọng được thêm vào system prompt

AgentMcpServerSpec

Chỉ định MCP server khả dụng cho một subagent. Có thể là tên server (string tham chiếu tới một server trong config mcpServers của parent) hoặc một record cấu hình server inline map tên server sang config.

type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

Trong đó McpServerConfigForProcessTransport là McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig.

SettingSource

Kiểm soát SDK load settings từ nguồn cấu hình filesystem nào.

type SettingSource = "user" | "project" | "local";

Value	Description	Location
'user'	Settings toàn cục của user	~/.claude/settings.json
'project'	Settings project chia sẻ (version controlled)	.claude/settings.json
'local'	Settings project cục bộ, gitignore khi Claude Code lưu một setting vào đó	.claude/settings.local.json

Hành vi mặc định

Khi settingSources bị bỏ qua hoặc undefined, query() load cùng bộ settings filesystem như CLI Claude Code: user, project, và local. Policy do endpoint quản lý luôn được load; server-managed settings được fetch khi session xác thực bằng credential tổ chức trên cấu hình đủ điều kiện. Xem What settingSources does not control để biết các input luôn được đọc bất kể option này, và cách tắt chúng.

Vì sao dùng settingSources

Tắt filesystem settings:

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

// Không load user, project, hoặc local settings từ đĩa
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

Load mọi filesystem settings tường minh:

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

const result = query({
  prompt: "Analyze this code",
  options: {
    settingSources: ["user", "project", "local"] // Load mọi settings
  }
});

Chỉ load một số nguồn setting cụ thể:

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

// Chỉ load project settings, bỏ qua user và local
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // Chỉ .claude/settings.json
  }
});

Môi trường testing và CI:

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

// Đảm bảo hành vi nhất quán trong CI bằng cách loại trừ local settings
const result = query({
  prompt: "Run tests",
  options: {
    settingSources: ["project"], // Chỉ settings chia sẻ theo team
    permissionMode: "bypassPermissions",
    allowDangerouslySkipPermissions: true
  }
});

Ứng dụng chỉ dùng SDK:

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

// Định nghĩa mọi thứ bằng code.
// Truyền [] để không dùng nguồn setting filesystem.
const result = query({
  prompt: "Review this PR",
  options: {
    settingSources: [],
    agents: {
      /* ... */
    },
    mcpServers: {
      /* ... */
    },
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

Load CLAUDE.md project instructions:

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

// Load project settings để bao gồm CLAUDE.md
const result = query({
  prompt: "Add a new feature following project conventions",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Dùng system prompt của Claude Code
    },
    settingSources: ["project"], // Load CLAUDE.md từ project directory
    allowedTools: ["Read", "Write", "Edit"]
  }
});

Thứ tự ưu tiên settings

Khi nhiều nguồn được load, settings được merge theo thứ tự ưu tiên này (cao nhất tới thấp nhất):

1. Local settings (.claude/settings.local.json)
2. Project settings (.claude/settings.json)
3. User settings (~/.claude/settings.json)

Các option lập trình như agents, allowedTools, và settings override user, project, và local filesystem settings. Managed policy settings có ưu tiên cao hơn programmatic options.

PermissionMode

type PermissionMode =
  | "default" // Hành vi permission tiêu chuẩn
  | "acceptEdits" // Tự động chấp thuận file edit
  | "bypassPermissions" // Bỏ qua kiểm tra permission; rule ask tường minh vẫn hỏi
  | "plan" // Planning mode - khám phá mà không edit
  | "dontAsk" // Không hỏi permission, deny nếu chưa được duyệt trước
  | "auto"; // Model classifier tự chấp thuận hoặc deny permission prompt

CanUseTool

Function type permission tuỳ chỉnh để kiểm soát việc dùng tool.

Function này là thay thế của SDK cho permission prompt tương tác: nó chỉ được gọi khi luồng đánh giá permission rơi xuống một prompt. Lời gọi tool đã được chấp thuận bởi một entry allowedTools, một allow rule trong settings, hoặc permission mode, như acceptEdits hoặc bypassPermissions, không bao giờ gọi nó. Để chặn mọi lời gọi tool, dùng PreToolUse hook thay vào đó.

AskUserQuestion, MCP tool đánh dấu requiresUserInteraction, và connector tool tổ chức của bạn đặt là ask vẫn chạm tới function này kể cả khi một allow rule khớp. Ở mode dontAsk các lời gọi này bị deny thay vào đó, không gọi function.

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    decisionReason?: string;
    toolUseID: string;
    agentID?: string;
    requestId: string;
  }
) => Promise<PermissionResult | null>;

Option	Type	Description
signal	AbortSignal	Báo hiệu nếu operation cần bị huỷ
suggestions	PermissionUpdate[]	Gợi ý cập nhật permission để người dùng không bị hỏi lại cho tool này. Prompt Bash gồm một gợi ý với destination localSettings, nên trả về nó trong updatedPermissions sẽ ghi rule vào .claude/settings.local.json và giữ nguyên qua các session.
blockedPath	string	Đường dẫn file gây ra permission request, nếu có
decisionReason	string	Giải thích vì sao permission request này được kích hoạt
toolUseID	string	Định danh duy nhất cho lời gọi tool cụ thể này trong message assistant
agentID	string	Nếu chạy trong một sub-agent, ID của sub-agent đó
requestId	string	request_id của envelope control_request. Một control_response mà ứng dụng của bạn gửi ngoài SDK, ví dụ một HTTP POST đã ký, phải echo lại giá trị này để process Claude Code khớp reply với request

Callback thường resolve request bằng cách trả về một PermissionResult, thứ SDK ghi lại qua transport của nó như control_response. Chỉ trả về null khi ứng dụng của bạn đã tự gửi control_response cho request này qua kênh riêng, echo lại requestId; lúc đó SDK bỏ qua việc ghi response vào transport của nó. Trả về null trong mọi trường hợp khác sẽ để lời gọi tool bị block vô thời hạn, vì không có control_response nào được gửi và permission prompt không có timeout.

Option requestId và giá trị trả về null yêu cầu Claude Code v2.1.199 trở lên.

PermissionResult

Kết quả của một permission check.

type PermissionResult =
  | {
      behavior: "allow";
      updatedInput?: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: "deny";
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };

ToolConfig

Cấu hình hành vi built-in tool.

type ToolConfig = {
  askUserQuestion?: {
    previewFormat?: "markdown" | "html";
  };
};

Field	Type	Description
askUserQuestion.previewFormat	'markdown' | 'html'	Kích hoạt field preview trên option AskUserQuestion và đặt định dạng nội dung của nó. Khi không đặt, Claude không emit preview

McpServerConfig

Cấu hình cho MCP server.

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

McpStdioServerConfig

type McpStdioServerConfig = {
  type?: "stdio";
  command: string;
  args?: string[];
  env?: Record<string, string>;
};

McpSSEServerConfig

type McpSSEServerConfig = {
  type: "sse";
  url: string;
  headers?: Record<string, string>;
};

McpHttpServerConfig

type McpHttpServerConfig = {
  type: "http";
  url: string;
  headers?: Record<string, string>;
};

McpSdkServerConfigWithInstance

type McpSdkServerConfigWithInstance = {
  type: "sdk";
  name: string;
  instance: McpServer;
};

McpClaudeAIProxyServerConfig

type McpClaudeAIProxyServerConfig = {
  type: "claudeai-proxy";
  url: string;
  id: string;
};

SdkPluginConfig

Cấu hình để load plugin trong SDK.

type SdkPluginConfig = {
  type: "local";
  path: string;
  skipMcpDiscovery?: boolean;
};

Field	Type	Description
type	'local'	Phải là 'local' (hiện chỉ hỗ trợ plugin local)
path	string	Đường dẫn tuyệt đối hoặc tương đối tới thư mục plugin
skipMcpDiscovery	boolean	Khi true, SDK load skill, hook, agent, và command từ plugin này nhưng không đọc .mcp.json hay mcpServers trong manifest của nó. Đặt cái này khi ứng dụng của bạn tự quản lý kết nối MCP của plugin.

Ví dụ:

plugins: [
  { type: "local", path: "./my-plugin" },
  { type: "local", path: "/absolute/path/to/plugin" }
];

Để biết thông tin đầy đủ về tạo và dùng plugin, xem Plugins.

Message Types

SDKMessage

Union type của mọi message có thể trả về bởi query.

type SDKMessage =
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage
  | SDKStatusMessage
  | SDKLocalCommandOutputMessage
  | SDKHookStartedMessage
  | SDKHookProgressMessage
  | SDKHookResponseMessage
  | SDKPluginInstallMessage
  | SDKToolProgressMessage
  | SDKAuthStatusMessage
  | SDKTaskNotificationMessage
  | SDKTaskStartedMessage
  | SDKTaskProgressMessage
  | SDKTaskUpdatedMessage
  | SDKBackgroundTasksChangedMessage
  | SDKThinkingTokensMessage
  | SDKSessionStateChangedMessage
  | SDKWorkerShuttingDownMessage
  | SDKCommandsChangedMessage
  | SDKNotificationMessage
  | SDKFilesPersistedEvent
  | SDKToolUseSummaryMessage
  | SDKMemoryRecallMessage
  | SDKRateLimitEvent
  | SDKElicitationCompleteMessage
  | SDKPermissionDeniedMessage
  | SDKPromptSuggestionMessage
  | SDKAPIRetryMessage
  | SDKMirrorErrorMessage
  | SDKInformationalMessage
  | SDKConversationResetMessage;

SDKAssistantMessage

Message phản hồi của assistant.

type SDKAssistantMessage = {
  type: "assistant";
  uuid: UUID;
  session_id: string;
  message: BetaMessage; // Từ Anthropic SDK
  parent_tool_use_id: string | null;
  error?: SDKAssistantMessageError;
  aborted?: true;
  timestamp?: string;
};

Field message là một BetaMessage từ Anthropic SDK. Nó gồm các field như id, content, model, stop_reason, và usage.

SDKAssistantMessageError là một trong: 'authentication_failed', 'oauth_org_not_allowed', 'billing_error', 'rate_limit', 'overloaded', 'invalid_request', 'model_not_found', 'server_error', 'max_output_tokens', hoặc 'unknown'. 'model_not_found' nghĩa là model được chọn không tồn tại hoặc không khả dụng cho account hoặc deployment của bạn. 'overloaded' nghĩa là API trả về 529 vì server đang quá tải, khác với 'rate_limit', là một 429 chống lại quota của bạn.

aborted là true khi một interrupt hoặc abort cắt cụt message assistant trước khi stream hoàn tất: message không có stop_reason và nội dung có thể kết thúc giữa chừng. Field này vắng mặt trên message hoàn tất bình thường. Nó yêu cầu Agent SDK v0.3.214 trở lên.

timestamp là thời gian ISO 8601 khi nội dung của message hoàn tất sinh trên process đã tạo ra nó. Giá trị lấy từ đồng hồ của máy đó, nên chỉ dùng nó để hiển thị và đừng sắp xếp message theo nó. Một turn API có thể tạo ra nhiều message assistant chia sẻ cùng message.id, mỗi cái có timestamp riêng. Khi field vắng mặt, dùng thời gian bạn nhận message làm phương án dự phòng.

SDKUserMessage

Message input của user.

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id?: string;
  message: MessageParam; // Từ Anthropic SDK
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
};

Đặt shouldQuery thành false để thêm message vào transcript mà không kích hoạt một turn assistant. Message được giữ lại và merge vào message user kế tiếp có kích hoạt turn. Dùng cái này để chèn context, ví dụ output của một lệnh bạn chạy ngoài luồng, mà không tốn một lời gọi model.

Trên một message mang khối tool_result, tool_use_result là object output có cấu trúc của tool thay vì text gửi cho model. Hình dạng của nó phụ thuộc vào tool được nêu tên bởi khối tool_use khớp, nên field được gõ kiểu unknown; các hình dạng built-in được liệt kê dưới Tool Output Types.

Với tool Agent, tool_use_result là AgentOutput. Trên một kết quả completed, content chứa báo cáo của subagent mà không có ID agent và trailer usage mà Claude Code thêm vào text tool_result, nên hãy render từ tool_use_result thay vì parse text đó.

SDKUserMessageReplay

Message user được replay với UUID bắt buộc.

type SDKUserMessageReplay = {
  type: "user";
  uuid: UUID;
  session_id: string;
  message: MessageParam;
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
  isReplay: true;
};

Một turn user được chèn từ bên ngoài session, với origin thuộc loại peer hoặc channel, tới stream dưới dạng replay bất kể nó được gửi trong lúc một turn đang chạy hay khởi động một turn mới khi session đang idle. Trước v2.1.207, một turn được chèn khi session đang idle không tạo ra message nào trên stream và chỉ xuất hiện khi bạn đọc lại transcript.

SDKResultMessage

Message kết quả cuối cùng.

type SDKResultMessage =
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      api_error_status?: number | null;
      num_turns: number;
      result: string;
      stop_reason: string | null;
      ttft_ms?: number;
      ttft_stream_ms?: number;
      user_message_uuid?: string;
      request_sent_wall_ms?: number;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      structured_output?: unknown;
      deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };
      terminal_reason?: TerminalReason;
      fast_mode_state?: FastModeState;
      fast_mode_disabled_reason?: FastModeDisabledReason;
      origin?: SDKMessageOrigin;
    }
  | {
      type: "result";
      subtype:
        | "error_max_turns"
        | "error_during_execution"
        | "error_max_budget_usd"
        | "error_max_structured_output_retries";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      stop_reason: string | null;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      errors: string[];
      terminal_reason?: TerminalReason;
      fast_mode_state?: FastModeState;
      fast_mode_disabled_reason?: FastModeDisabledReason;
      origin?: SDKMessageOrigin;
    };

Một số field trên result mang chi tiết chẩn đoán ngoài subtype:

• api_error_status: mã HTTP status của lỗi API đã kết thúc hội thoại. Vắng mặt hoặc null khi turn kết thúc mà không có lỗi API.
• ttft_ms: thời gian tới token đầu tiên tính bằng mili giây, đo khi message assistant hoàn chỉnh đầu tiên tới. Chỉ có trên nhánh success.
• ttft_stream_ms: thời gian (ms) tới event stream message_start đầu tiên, khi response stream mở ra. Thấp hơn ttft_ms; khoảng cách giữa hai giá trị là thời gian dùng để stream message đầu tiên. Chỉ có trên nhánh success.
• user_message_uuid: uuid của SDKUserMessage đã bắt đầu turn này, được echo lại để bạn khớp result với message đã gửi (từ v2.1.216). Yêu cầu Claude Code v2.1.216 trở lên. Chỉ có trên nhánh success, cùng với request_sent_wall_ms; vắng mặt trên result lỗi API, lời gọi subagent, và turn tổng hợp như các turn theo lịch.
• request_sent_wall_ms: mili giây epoch tại thời điểm Claude Code gửi request API, để join với timestamp phía server. Chỉ có cùng với user_message_uuid.
• terminal_reason: vì sao vòng lặp kết thúc. Một trong "completed", "max_turns", "tool_deferred", "aborted_streaming", "aborted_tools", "hook_stopped", "stop_hook_prevented", "background_requested", "blocking_limit", "rapid_refill_breaker", "prompt_too_long", "image_error", "model_error", "api_error", "malformed_tool_use_exhausted", "budget_exhausted", "structured_output_retry_exhausted", "tool_deferred_unavailable", hoặc "turn_setup_failed".
• fast_mode_state: một trong "on", "off", hoặc "cooldown".
• fast_mode_disabled_reason: vì sao fast mode hiện không khả dụng (từ v2.1.219). Vắng mặt khi không có gì chặn fast mode, dù một request vẫn có thể chạy ở tốc độ chuẩn. Trong lúc cooldown sau một rate limit fast mode, Claude Code báo fast_mode_state: "cooldown" không kèm mã lý do và tự bật lại fast mode khi cooldown hết hạn. Yêu cầu Claude Code v2.1.219 trở lên.