Cursor SDK 教程：使用 TypeScript 运行编码代理

Cursor 于 2026 年 4 月下旬发布了其 TypeScript SDK 公测版。该包以 @cursor/sdk 的形式发布，可在脚本、CI 任务和后端服务等 Node 环境中运行。

与在编辑器中使用 Cursor 的主要区别在于任务的触发位置。不再是您自己打开聊天并输入提示，而是由您的代码创建代理、发送任务、流式接收事件、等待结果并处理错误。

在本教程中，我们将完成 SDK 的安装、运行本地快速上手，然后构建一个主项目：一个在云端修复 GitHub 仓库中的错误并打开拉取请求的代理。为了便于观察 SDK 的流程，我特意将错误设置得很小。随后，我们将介绍在复用该模式前所需的扩展点和安全检查。云端项目配套有一个示例仓库，包含启动脚本与目标项目。

SDK 仍处于公测阶段，如要在长期项目中复用本文代码，请先查阅官方文档。

什么是 Cursor SDK？

Cursor SDK 是一个 TypeScript 包 @cursor/sdk，可让您在代码中创建并运行 Cursor 代理。它提供对以下内容的访问：

• 本地与云端的代理运行。
• Cursor 的代码库工具，包括索引、搜索、grep、MCP 服务器、技能、钩子和子代理。
• 您 Cursor 账户可用的模型，包括Composer 2、GPT-5.5 和 Claude。

SDK 使用与 Cursor IDE、CLI 和 Web 应用相同的代理系统，不同在于您通过 TypeScript 调用它。

何时使用 SDK

SDK 适合那些应由代码发起、而不是由人在编辑器中输入的任务。我会在以下场景使用它：CI 任务让代理检查失败的测试、Webhook 为 Bug 修复创建分支、或内部工具从表单运行固定的代理任务。

SDK 与 Cursor 应用的对比

SDK 是使用 Cursor 代理的另一种方式，与 Cursor IDE 和 cursor agent CLI 并列。

编辑器对话用 IDE。终端提示用 CLI。当需要由 TypeScript 代码创建代理、发送任务并处理结果时，用 SDK。如上所述，CLI 不支持外部提供商密钥；SDK 同样仅通过 Cursor API 密钥进行认证。

Cursor SDK 的组成

在编写代码前，先了解 SDK 暴露的几个对象和运行时选项会更有帮助。

Cursor SDK 在三种运行时下的架构。图片作者自制。

三种运行时

SDK 支持在三个位置运行代理。

本文将使用本地与 Cursor 云端。上表中的自建云端主要面向企业版方案。通过传入的配置键即可切换 SDK 代码：local 或 cloud。

运行时、工具与模型

一次运行由三部分构成。运行时决定执行位置。代理工具包括索引、搜索、MCP 工具调用、技能、钩子与子代理。模型通过 model: { id: "composer-2" } 或您账户可用的其他 ID 选择。

这些都在代理配置中设置。

Agent 与 Run

SDK 中的两个主要对象是 Agent 和 Run。Agent 保存会话状态、工作区配置与模型设置。Run 则是发送给该代理的一次提示，具有独立的流、状态、结果和取消句柄。

这种区分很重要，因为云端代理强制每个代理同一时间只允许一个活动的运行。如果您在第一个仍在进行时发送第二个提示，API 会返回 409 agent_busy。要并行运行任务，应创建多个代理，而不是在同一个代理上创建多个运行。

流式事件

每次运行都通过 run.stream() 暴露一个事件流，这是一个异步迭代器。每个事件都有 type 字段。在当前公测版中，SDK 会发出 system、user、assistant、tool_call、thinking、status、request 和 task 事件。目前没有记录在案的 connection:reconnecting 事件；重连由 SDK 内部处理。

若需更底层的更新，agent.send() 也接受 onDelta 和 onStep 回调。

设置 Cursor SDK

所需仅为 Node、TypeScript 和一个 Cursor API 密钥。

先决条件

您需要：

• Node.js 22 或更高版本。该包正式支持 Node 18 或更高版本，但 Node 22 与官方示例一致，并支持用于加载 --env-file 的 .env 标志。

• 用于云端代理的 Cursor Pro（$20/月）或更高方案账户。

• 基础的 TypeScript 知识。

• tsx 以免编译即可运行 TypeScript。

安装 SDK 与 TypeScript 工具：

安装 SDK

在一个全新文件夹中：

npm init -y
npm install @cursor/sdk
npm install --save-dev typescript tsx @types/node技术支持

在 package.json 中添加 "type": "module" 以使用 ESM 导入。然后添加支持顶层 await 和显式异步释放的 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022", "ESNext.Disposable"],
    "strict": true,
    "esModuleInterop": true
  }
}技术支持

获取 Cursor API 密钥

该密钥最初在 cursor.com/dashboard/cloud-agents 下生成，但现已迁移至 cursor.com/dashboard/integrations。若某指南仍指向“Cloud Agents”，请改到 Integrations。

在 Integrations 中生成用户 API 密钥。图片作者自制。

在那里生成用户 API 密钥并将其保存为 CURSOR_API_KEY：

echo 'CURSOR_API_KEY=crsr_your_key_here' > .env技术支持

将 .env 加入 .gitignore。SDK 直接读取 process.env；它不会为您加载 .env 文件。

项目结构

文件夹布局：package.json、tsconfig.json、.env，以及用于脚本的 src/。需要时添加 .cursor/ 文件夹以放置钩子、技能与子代理。

您的第一个本地 Cursor 代理

第一个示例故意保持精简。它创建一个本地代理，发送一个提示，流式输出响应，最后释放代理。

创建本地代理

创建 src/01-quickstart.ts：

import { Agent, type SDKMessage } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});技术支持

Agent.create() 会在代理开始工作前返回一个句柄。 local: { cwd: process.cwd() } 将代理指向当前工作目录。SDK 支持异步释放；在教程代码中，我更倾向使用显式的 finally 块，以避免 await using 的版本兼容问题。

发送提示并流式输出响应

发送提示会返回一个 Run 对象，拥有自己的流与状态。此示例在 for await 循环中读取流，并仅打印助手文本。

try {
  const run = await agent.send(
    `Write a terminal-friendly summary for a screenshot.

Output exactly:
Local agent summary
- Purpose: demonstrates a local Cursor SDK agent.
- Key files: src/01-quickstart.ts, package.json, tsconfig.json.
- SDK action: creates an agent and streams assistant text.

Rules:
Print exactly those three bullets.
No Markdown bold.
No extra explanation.`,
  );

  for await (const event of run.stream()) {
    if (event.type !== "assistant") continue;
    for (const block of event.message.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  }

  const result = await run.wait();
  const duration = result.durationMs === undefined ? "" : `duration=${result.durationMs}ms`;
  console.log(`\n[done] status=${result.status}${duration}`);
} finally {
  await agent[Symbol.asyncDispose]();
}技术支持

代理会发出多种事件类型，包括 thinking、tool_call 和 status。本例仅筛选可见答案的 assistant 文本。event.message.content 有类型定义并可用于流式处理，但它是分块的，且可能包含工具调用。若您只需最终文本，可跳过流，待 run.wait() 后读取 result.result。durationMs 是公开但可选的，因此示例将其按可选处理。

处理错误

SDK 会抛出继承自 CursorAgentError 的类型化错误。常见情形包括 AuthenticationError（密钥错误）、ConfigurationError（模型 ID 无效）、RateLimitError、IntegrationNotConnectedError 和 NetworkError。

import { CursorAgentError } from "@cursor/sdk";

try {
  // ... agent code
} catch (error) {
  if (error instanceof CursorAgentError) {
    console.error([${error.code ?? "unknown"}] ${error.message});
    if (error.isRetryable) {
      console.error("Retryable. Try again in a moment.");
    }
  } else {
    throw error;
  }
}技术支持

isRetryable 标志是您的重试逻辑应当检查的。网络错误与限流可重试；配置错误与认证错误不可重试。

运行示例

保存文件，使用 Node 的 .env 加载器与 tsx 运行：

node --env-file=.env --import tsx/esm src/01-quickstart.ts技术支持

--env-file=.env 标志会在脚本启动前加载 CURSOR_API_KEY 。脚本应打印助手文本，然后是一行状态尾注。若出现认证错误，请检查 .env ，并确认密钥来自 Integrations 控制台生成。