用途
Cursor SDK(包名 @cursor/sdk)是 Cursor 提供的 TypeScript SDK,用于以编程方式运行 Cursor 智能体。同一套接口可驱动两种运行时:本地运行时在调用方机器上、针对当前工作目录和本地文件运行;云端运行时在 Cursor 托管或自托管的云基础设施上,针对新克隆的仓库运行,并可自动创建 PR。该技能面向希望基于 SDK 构建应用、脚本、CI 流水线或自动化的开发者,重点在于集成决策、常见失败模式规避和可扩展的实现模式。
主要能力
- 三种调用模式:
Agent.prompt(...)一次性调用;Agent.create(...)加agent.send(...)支持流式输出、多轮对话与生命周期操作;Agent.resume(...)跨进程恢复已有智能体。 - 运行观测:
run.stream()获取事件流,run.wait()获取最终结果;通过run.supports(...)判断当前运行时是否支持某项操作。 - 认证:通过
CURSOR_API_KEY环境变量或显式传入apiKey,支持用户 API Key 和团队服务账号 Key。 - 模型选择:可用
Cursor.models.list()查询可用模型,composer-2为多数集成的默认模型,auto由服务端选择。 - 运行查询:可通过
Agent.get、Agent.getRun、Agent.list按 ID 或运行时查询智能体与运行信息。 - MCP 服务器配置:支持 HTTP、stdio 等传输方式及本地/云端差异。
使用方式
基本流程为:设置 CURSOR_API_KEY,按需选择 Agent.prompt、Agent.create 加 send、或 Agent.resume,指定模型与运行时(本地用 local: { cwd },云端用 cloud: { repos }),然后消费流式事件并调用 wait() 获取终态。生产环境中应在 try/finally 中调用 [Symbol.asyncDispose]() 释放资源,或使用 await using 语法;应区分启动失败(CursorAgentError)与运行失败(result.status === "error"),并遵循 error.isRetryable 决定是否重试。
适用场景
适合构建代码审查机器人、定时巡检、聊天式代码问答、webhook 触发的自动化,以及本地开发循环和已有代码检出的 CI 流水线;云运行时更适合长时间任务、免值守自动化和自动创建 PR。
限制
该技能不涵盖 Cloud Agents REST API、.cursor/hooks.json 钩子、私有 worker/自托管云,以及其他语言的 SDK(目前没有官方非 TypeScript SDK,REST 是跨语言方案)。当前已文档化的差异包括:分离或重新加载的运行可能不支持 stream(),conversation() 可能为空;本地运行时中模型为必填,云端为可选;内联 mcpServers 在 resume 时不会持久化,需要再次传入。