Cursor SDK

Cursor 正式推出 Cursor SDK，标志着编程智能体从面向个人开发者的交互式工具，正式演进为面向组织的程序化基础设施。

通过 Cursor SDK，开发者只需几行 TypeScript 代码，即可调用驱动 Cursor 桌面应用、CLI 和 Web 应用的同一套运行时、框架和模型来构建智能体。无论是本地快速迭代，还是云端大规模自动化部署，Cursor SDK 都提供了统一且强大的解决方案。

目前，Cursor SDK 已面向所有用户开放公开 Beta。

核心优势：消除构建智能体的复杂性

构建生产级的编程智能体通常涉及繁琐的工程工作：安全沙箱、持久化状态管理、环境配置、上下文索引等。Cursor SDK 屏蔽了这些底层复杂性，让团队能够专注于业务逻辑。

1. 生产就绪的云基础设施

通过 SDK发起的云端会话，运行在与 Cursor 云端智能体相同的优化运行时之上：

• 专用 VM 隔离：每个智能体拥有独立的沙箱环境、仓库克隆副本及配置完整的开发环境。
• 断点续传：即使本地网络中断或电脑休眠，云端智能体仍持续运行。你可以随时重新连接查看进度。
• 自动化交付：任务完成后，智能体可自动创建 PR、推送分支，甚至附加演示截图。

// 启动云端智能体执行任务
const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "gpt-5.5" },
  cloud: {
    repos: [{ url: "https://github.com/cursor/cookbook", startingRef: "main" }],
    autoCreatePR: true, // 自动创建 PR
  },
});

const run = await agent.send("Fix the auth token expiry bug");
console.log(`Started ${run.id}`);

// 稍后获取结果
const result = await (
  await Agent.getRun(run.id, { runtime: "cloud", agentId: run.agentId })
).wait();
console.log(result.git?.branches[0]?.prUrl);

2. 灵活的部署模式

同一个 SDK 支持多种运行时环境，满足不同场景需求：

• Cloud（云端）：利用 Cursor 优化的专用 VM，适合长时间运行、高隔离要求的任务。
• Local（本地）：在本地机器运行，适合快速调试和迭代。
• Self-hosted（自托管）：将代码执行保留在企业内网，满足严格的数据合规要求。

3. 完整的 Cursor 运行框架

SDK 智能体继承了 Cursor 核心产品的所有高级能力：

• 智能上下文管理：内置代码库索引、语义搜索和即时 grep，帮助智能体精准定位代码。
• MCP Servers 支持：通过 .cursor/mcp.json 或内联配置，连接外部工具和数据源。
• Skills 自动加载：自动读取仓库 .cursor/skills/ 目录中的技能定义。
• Hooks 扩展：通过 .cursor/hooks.json 观察和控制智能体循环。
• Subagents（子智能体）：主智能体可将子任务委派给具名子智能体，实现复杂任务的并行处理。

基于任意模型，平衡成本与性能

Cursor SDK 支持访问 Cursor 平台的所有模型。开发者可以根据任务复杂度动态路由到最佳模型：

• Composer 2：专为编程打造的前沿模型，以通用模型一小部分的成本实现卓越性能，是大多数编程任务的首选。
• GPT-5.5 / Claude 4 等：针对超高难度推理任务，可切换至更强大的通用模型。

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" }, // 轻松切换模型
  local: { cwd: process.cwd() },
});

开发者正在构建什么？

随着 SDK 的开放，各团队正在探索多样化的应用场景：

• CI/CD 自动化智能体：直接由流水线触发，自动总结代码变更、定位 CI 失败根因，并在 PR 中提交修复建议。
• 内部数据查询平台：为 GTM（Go-To-Market）团队构建无代码界面，通过自然语言查询产品数据。
• 嵌入式客户体验：将 Cursor 智能体能力嵌入面向客户的产品中，让用户在宿主应用内即可获得即时辅助。

快速开始

安装 SDK：

npm install @cursor/sdk

极简示例（本地运行）：

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

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

const run = await agent.send("Summarize what this repository does");

for await (const event of run.stream()) {
  console.log(event);
}

示例项目与资源

为了帮助开发者快速上手，Cursor 在 GitHub 公开仓库中提供了多个入门项目：

• Quick Start：极简 Node.js 示例，展示本地智能体的创建与流式响应。
• Prototyping Tool：Web 应用，用于在云端沙箱中快速启动智能体并迭代创意。
• Kanban Board：智能体驱动的看板，工程师拖动卡片即可触发智能体完成任务并提交 PR。
• Coding Agent CLI：轻量级命令行工具，从终端直接启动 Cursor 智能体。