名称: TypeScript SDK 参考描述: TypeScript Agent SDK 的全面参考，包含函数、类型和接口，用于程序化 Claude Code 交互允许的工具:

读取
写入
编辑
任务

TypeScript SDK 参考

一个全面的参考，用于使用 Anthropic Agent SDK (TypeScript) 构建应用程序，实现与 Claude Code 的程序化交互和自定义工具集成。

安装

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

快速开始

核心函数

函数	目的	关键用例
`query()`	Claude Code 交互的主要接口	发送提示、流式响应、管理多轮对话
`tool()`	使用类型安全模式定义 MCP 工具	使用 Zod 验证创建自定义代理工具
`createSdkMcpServer()`	创建进程内 MCP 服务器	在应用程序中原生托管工具

示例: 基本查询

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

const result = query({
  prompt: "分析这段代码并建议改进",
  options: {
    allowedTools: ['Read', 'Grep'],
    model: 'claude-opus'
  }
});

for await (const message of result) {
  if (message.type === 'assistant') {
    console.log(message.message.content);
  }
}

主要函数参考

`query()`

流式传输 Claude Code 响应，支持完整消息类型。返回一个 SDKMessage 对象的异步生成器。

参数:

prompt: 字符串或消息的异步可迭代对象（流式模式）
options: 配置对象（见下方选项）

返回: Query 对象（扩展 AsyncGenerator<SDKMessage, void>）

关键方法:

.interrupt() – 中断流式传输（仅限流式模式）
.setPermissionMode(mode) – 动态更改权限（仅限流式模式）

`tool()`

使用 Zod 模式创建类型安全的 MCP 工具定义。处理器接收验证后的输入并必须返回 CallToolResult。

参数:

name: 工具标识符
description: 自然语言描述
inputSchema: 定义输入的 Zod 模式
handler: 异步函数 (args: z.infer<Schema>, extra?: unknown) => Promise<CallToolResult>

返回: SdkMcpToolDefinition<Schema>

`createSdkMcpServer()`

创建进程内 MCP 服务器以托管自定义工具。在同一 Node.js 进程中运行，无子进程开销。

参数:

name: 服务器标识符
version: 可选语义版本
tools: 来自 tool() 的工具定义数组

返回: McpSdkServerConfigWithInstance（准备用于 mcpServers 选项）

关键配置选项

基本选项

选项	类型	默认	目的
`allowedTools`	`string[]`	所有可用	限制 Claude 可使用的工具
`disallowedTools`	`string[]`	`[]`	明确阻止工具
`model`	`string`	CLI 默认	覆盖 Claude 模型（例如 `'claude-opus'`）
`cwd`	`string`	`process.cwd()`	操作的工作目录
`abortController`	`AbortController`	新实例	控制任务取消

高级选项

选项	类型	默认	目的
`systemPrompt`	字符串或预设对象	无	自定义系统指令或 Claude Code 预设
`agents`	`Record<string, AgentDefinition>`	`undefined`	以编程方式定义具有自定义提示的子代理
`mcpServers`	`Record<string, McpServerConfig>`	`{}`	连接 stdio、SSE、HTTP 或 SDK MCP 服务器
`settingSources`	`('user' \| 'project' \| 'local')[]`	`[]`	加载文件系统设置（CLAUDE.md, settings.json）
`permissionMode`	`PermissionMode`	`'default'`	`'default'`、`'acceptEdits'`、`'bypassPermissions'` 或 `'plan'`
`maxThinkingTokens`	`number`	`undefined`	扩展思考的令牌限制
`maxTurns`	`number`	`undefined`	停止前的最大对话轮次
`resume`	`string`	`undefined`	通过 ID 恢复先前的会话
`forkSession`	`boolean`	`false`	恢复时分支到新会话而不是继续

消息类型概述

query() 生成器产生 SDKMessage 对象。常见类型：

消息类型	何时发出	关键字段
`'system'`	会话初始化	`tools`、`model`、`permissionMode`、`slash_commands`
`'user'`	用户输入发送	`message` (APIUserMessage)、`uuid`
`'assistant'`	Claude 响应	`message` (APIAssistantMessage 带有 content/tool_use)
`'result'`	查询完成	`subtype` (‘success’ 或错误)、`usage`、`total_cost_usd`
`'stream_event'`	部分流式数据	`event`（仅当 `includePartialMessages: true` 时）

查看消息类型参考获取完整定义。

类型参考概述

核心配置类型

Options – 查询配置，包含 20+ 属性（工具、MCP、权限、执行）
PermissionMode – 控制执行权限：'default'、'acceptEdits'、'bypassPermissions'、'plan'
SettingSource – 文件系统配置范围：'user'、'project'、'local'

代理和工具类型

AgentDefinition – 子代理配置：description、prompt、tools、model 覆盖
SdkMcpToolDefinition – tool() 函数的输出，带有 Zod 模式绑定
McpServerConfig – stdio、SSE、HTTP 或 SDK 服务器配置的联合

MCP 服务器配置

配置类型	传输	用例
`McpStdioServerConfig`	stdio（子进程）	外部工具、沙箱化
`McpSSEServerConfig`	服务器发送事件	远程工具、发布/订阅模式
`McpHttpServerConfig`	HTTP	基于 REST 的工具、云集成
`McpSdkServerConfigWithInstance`	进程内	自定义工具、无子进程开销

钩子类型

HookEvent – 事件名称：PreToolUse、PostToolUse、Notification、UserPromptSubmit、SessionStart、SessionEnd 等
HookCallback – 接收钩子输入并返回决策的异步函数
HookInput – 所有钩子输入类型的联合；每个都扩展 BaseHookInput

查看类型参考获取详细类型定义。

工具输入/输出参考

内置工具输入

所有工具名称映射到输入模式：

工具	目的	关键输入
`Task`	委托给子代理	`description`、`prompt`、`subagent_type`
`Bash`	运行 shell 命令	`command`，可选 `timeout`、`run_in_background`
`Read`	读取文件/图像/PDF	`file_path`，可选 offset/limit
`Write` / `Edit`	修改文件	`file_path`、`content` 或 old/new 字符串
`Glob`	模式匹配	`pattern`，可选 `path`
`Grep`	正则表达式搜索	`pattern`，可选过滤器（glob、type、-B/-A/-C）
`WebFetch`	获取和分析 URL	`url`、`prompt` 用于 AI 分析
`WebSearch`	网络搜索	`query`，可选域过滤器
`NotebookEdit`	Jupyter 笔记本	`notebook_path`、`new_source`、`edit_mode`
`TodoWrite`	任务跟踪	`todos` 数组，带有 status、content、activeForm

查看工具参考获取完整的输入/输出模式和示例。

常见模式

带进度的流式传输

const result = query({
  prompt: "您的任务在此",
  options: {
    includePartialMessages: true,
    permissionMode: 'bypassPermissions'
  }
});

for await (const msg of result) {
  if (msg.type === 'stream_event') {
    // 处理流式事件
    console.log('流式传输:', msg.event);
  } else if (msg.type === 'result') {
    console.log('成本:', msg.total_cost_usd, '使用量:', msg.usage);
  }
}

自定义 MCP 工具

import { tool, createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
import { z } from 'zod';

const myTool = tool(
  'my-calculator',
  '两个数字相加',
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: 'text', text: `结果: ${a + b}` }]
  })
);

const server = createSdkMcpServer({
  name: 'my-tools',
  tools: [myTool]
});

const result = query({
  prompt: "使用 my-calculator 计算 5 + 3",
  options: {
    mcpServers: { 'my-tools': server }
  }
});

加载项目设置

const result = query({
  prompt: "添加一个遵循项目约定的功能",
  options: {
    systemPrompt: {
      type: 'preset',
      preset: 'claude_code'  // 启用 Claude Code 系统提示
    },
    settingSources: ['project'],  // 加载 .claude/settings.json 和 CLAUDE.md
    allowedTools: ['Read', 'Write', 'Edit', 'Bash']
  }
});

TypeScriptSDK参考Skill TypeScriptSDKReference