使用Cursor SDK构建编程代理

Cursor 发布了 Cursor SDK，这是一个新的工具集，允许开发者以编程方式构建和使用与 Cursor 桌面应用、CLI 和 Web 应用相同的代理运行时。通过这个 SDK，开发者可以用几行 TypeScript 代码创建代理，并在本地机器、Cursor 的云基础设施或自托管的 worker 上运行。

SDK 的核心是 Agent 类，开发者可以创建一个 Agent 实例，指定 API 密钥、模型和运行环境（本地或云）。然后通过 send 方法发送提示，并流式接收响应。例如，一个简单的代码示例如下：

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);
}

对于生产环境，SDK 提供了云会话功能。每个云代理在专用的虚拟机上运行，具有强沙箱隔离、仓库克隆和完整的开发环境配置。代理可以在笔记本电脑休眠或网络断开时继续运行，任务完成后可以自动创建 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,
  },
});

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);

SDK 基于更新的 Cloud Agents API，云代理运行会显示在 Cursor 的代理窗口和 Web 应用中，开发者可以启动任务后在 Cursor 中检查进度或接管工作。

Cursor SDK 提供了与 Cursor 全平台相同的完整代理工具链：

• 智能上下文管理：包括代码库索引、语义搜索和即时 grep，帮助代理更快、更高效地达到预期结果。
• MCP 服务器：允许代理通过 stdio 或 HTTP 连接外部工具和数据源，配置方式可以是 .cursor/mcp.json 文件或内联传递。
• 技能（Skills）：代理自动从仓库的 .cursor/skills/ 目录中获取技能。
• 钩子（Hooks）：通过 .cursor/hooks.json 文件在云、自托管和本地环境中观察、控制和扩展代理循环。
• 子代理（Subagents）：将子任务委托给具有独立提示和模型的命名子代理，由主代理通过 Agent 工具生成。

SDK 支持所有 Cursor 中可用的模型，包括专用的编码模型 Composer 2，该模型以较低的成本实现了前沿性能。开发者可以通过更改一个字段来为任务选择最佳的模型，平衡成本和能力。

目前，团队已经在使用 Cursor SDK 构建各种自定义代理。例如，从 CI/CD 管道中直接启动编程代理，总结变更、识别 CI 失败的根因并更新 PR 修复。其他团队正在构建内部应用程序，让非技术团队无需编写代码即可查询产品数据。一些客户甚至将 Cursor 直接嵌入面向最终用户的产品中。

Cursor 提供了几个示例项目，包括快速入门、原型工具、看板应用和 CLI 工具，开发者可以在公共 GitHub 仓库中找到这些项目并扩展使用。

Cursor SDK 目前处于公开测试阶段，所有用户均可使用。计费基于标准的令牌消耗定价。安装方法：运行 npm install @cursor/sdk，然后使用 Cursor 的原生 /sdk 技能获取构建指导。Cursor 计划继续投资于 SDK，使其更易于开发者在更多语言、工作流和部署模式中构建编程代理。