TypeScript SDK 入门

包名为 @cursor/sdk，需要 Node.js 22.13 或以上。包中包含平台对应的 sandbox 和 ripgrep 二进制；不要把它当成纯浏览器依赖。

npm install @cursor/sdk
export CURSOR_API_KEY="your-key"

SDK 接受用户和服务账号 API key，尚不支持 Team Admin key。认证优先级是显式 apiKey、CURSOR_API_KEY、SDK 保存的浏览器登录；不会自动读取桌面 Cursor App 的登录凭据。

首次本地运行

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

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

const run = await agent.send("Summarize what this repository does");
const result = await run.wait();
console.log(result.status, result.result);

此例使用官方当前示例模型，实际可用 ID 应通过模型目录发现。本地首次 send 前必须确定模型。默认工具无需人工批准、沙箱关闭，运行前按SDK 权限选择需要的限制。

await using 在作用域退出时异步释放资源。也可显式 await agent[Symbol.asyncDispose]()；agent.close() 只启动释放，不等待完成。一次性调用可用 Agent.prompt(message, options)，它创建、运行、等待并释放，不提供第二轮会话。

云端运行

用 cloud 代替 local，repos 指定远程仓库；空数组或省略 repos 可请求无仓库 VM。省略整个 cloud 则选择本地运行，不是无仓库云端。无仓库功能需要账号/团队开放，仓库范围 key 不能创建，使用用户或不限制仓库的服务账号 key。

SDK 创建的云端任务默认被普通任务列表过滤，在网页或 Agents Window 选择 Filter > Source > SDK 查看。

浏览器认证

Cursor.auth.login() 打开浏览器并保存用户 key，默认有效期 90 天，文件为 ~/.cursor/sdk/auth.json。Cursor.auth.status() 查看状态，Cursor.auth.logout() 退出。

login 可设置 openBrowser、onLoginUrl、signal、store、apiKeyName 和 apiKeyTtlMs。SSH 或 NO_OPEN_BROWSER 下不会自动打开浏览器；store 设 null 时仅从返回值取得 key。不要把 SDK credential store 与桌面 App 登录混淆。

单文件打包

普通构建会惰性加载内部模块，单文件打包可能在首次创建时出现 Cannot find module './986.js'。可用 @cursor/sdk/bundled，SQLite 对应 @cursor/sdk/bundled/sqlite；Bun 自动选择 flat build。

bun build --compile main.ts --outfile my-agent

flat build 在 Node 中没有 SQLite store，应配置 JsonlLocalAgentStore。普通 Node 应用继续使用标准入口。原生二进制不能放进 JS bundle，需要把平台 node_modules/@cursor/sdk-<os>-<arch>/ 放在可执行文件旁；缺失时搜索回退到 PATH 中的 rg，启用沙箱则抛 ConfigurationError。