Cursor 一直在 IDE 里用。你打开编辑器，按 Cmd+K，Agent 帮你写代码。很好用，但有个限制——你只能坐在 Cursor 编辑器前面用。

现在变了。Cursor 发布了 @cursor/sdk，一个 TypeScript SDK（公测阶段），让你从自己的代码里直接调用 Cursor 的 AI Agent。不是模拟，不是套壳，是同一个 Agent——IDE 里用的那个。

本文提纲

1. Cursor SDK 解决什么问题
2. 三种运行时：本地、云端、自托管
3. 核心能力一览
4. 代码示例：5 个典型场景
5. REST API：不用 TypeScript 也能调
6. 和 Cursor IDE/CLI 的关系
7. 定价和限制

Cursor SDK 解决什么问题

之前你想用 Cursor 的 Agent 能力，只有两条路：
- Cursor IDE — 坐在编辑器前手动操作
- Cursor CLI — 终端里用 cursor agent 命令

两条路都是交互式的。你想把 Cursor Agent 嵌到 CI 流水线里？想写个脚本让 Agent 自动修 bug 再提 PR？想在 cron job 里让 Agent 每天检查代码质量？做不到。

SDK 就是来解决这个问题的。从"人在 Cursor 里用 Agent"变成"代码调用 Agent 自动干活"。

几个典型场景：
- CI 流水线里跑 Agent 做代码审查
- 批量修 issue：遍历 GitHub Issues，每个丢给一个 Agent
- 自动化工作流：定时让 Agent 扫一遍代码库做健康检查
- 构建自己的 AI 编程产品：底层用 Cursor Agent 的能力

三种运行时：本地、云端、自托管

同一个 Agent.create() 接口，三种运行环境，代码几乎一样：

本地运行（Local）：

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

Agent 在你的 Node.js 进程里跑，直接操作当前工作目录的文件。适合开发脚本、CI 检查、本地自动化。不需要额外资源，但 Agent 占你的机器。

云端运行（Cloud）：

const agent = await Agent.create({
  model: { id: "composer-2" },
  cloud: {
    repos: [{ url: "https://github.com/your-org/your-repo", startingRef: "main" }],
    autoCreatePR: true,
  },
});

Agent 跑在 Cursor 托管的 VM 上。你传入 GitHub 仓库 URL 和分支，Agent 在云端操作，完事自动创建 PR。适合跑重任务、并行多任务、不想占本地资源。

自托管池： 文档里提到了自托管的 Cloud 选项，适合企业用户在自己基础设施上跑。

关键点：切运行时只改一个配置项。从本地切到云端，不需要重写业务逻辑。

核心能力一览

子 Agent 是个亮点。 你可以预定义多个专业 Agent，主 Agent 根据任务需要自动调度：

const agent = await Agent.create({
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
  agents: {
    "code-reviewer": {
      description: "Expert code reviewer for quality and security.",
      prompt: "Review code for bugs, security issues, and proven approaches.",
      model: "inherit",
    },
    "test-writer": {
      description: "Writes tests for code changes.",
      prompt: "Write comprehensive tests for the given code.",
    },
  },
});

主 Agent 收到任务后，可以自行决定是调用 code-reviewer 还是 test-writer，或者两个都调。这是多 Agent 协作的轻量实现——不需要外部的编排框架，SDK 自带。

代码示例：5 个典型场景

1. 一句话提问（最简用法）：

const result = await Agent.prompt(
  "What does the auth middleware do?",
  { local: { cwd: process.cwd() } }
);
console.log(result);

Agent.prompt() 是一个便捷方法，创建 Agent、发送消息、等待结果，一步完成。适合一次性问答。

2. 流式输出（实时看 Agent 在干什么）：

const agent = await Agent.create({ local: { cwd: process.cwd() } });
const run = await agent.send("Find the bug in src/auth.ts");

for await (const event of run.stream()) {
  switch (event.type) {
    case "assistant":
      // Agent 输出的文本
      break;
    case "thinking":
      // Agent 的思考过程
      break;
    case "tool_call":
      // Agent 调用的工具和状态
      break;
    case "status":
      // 运行状态变化
      break;
  }
}

7 种事件类型：system、user、assistant、thinking、tool_call、status、task。覆盖了 Agent 运行的全生命周期。

3. 云端 Agent + 自动创建 PR：

const agent = await Agent.create({
  cloud: {
    repos: [{ url: "https://github.com/our-org/api", startingRef: "main" }],
    autoCreatePR: true,
  },
});

const run = await agent.send("Fix the null pointer exception in UserService.ts");
await run.wait();
// PR 自动创建

autoCreatePR: true 让云端 Agent 改完代码直接提 PR。你甚至不需要 clone 仓库。

4. 恢复已有会话：

const agent = await Agent.resume("bc-abc123");
const run = await agent.send("Also update the changelog");
await run.wait();

Agent 是持久化的。上次聊到一半的对话，用 Agent.resume() 接着来。

5. 接入 MCP 服务器：

const agent = await Agent.create({
  local: { cwd: process.cwd() },
  mcpServers: {
    docs: {
      type: "http",
      url: "https://example.com/mcp",
    },
    filesystem: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", process.cwd()],
    },
  },
});

Agent 自动获得 MCP 服务器提供的工具。HTTP 类型和 stdio 类型都支持。

REST API：不用 TypeScript 也能调

不是 TypeScript 项目？Cursor 同时提供了 REST API（api.cursor.com/v1/），支持任何语言。

关键端点：

认证用 Basic Auth，API Key 当用户名：

curl --request POST \
  --url https://api.cursor.com/v1/agents \
  -u YOUR_API_KEY: \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": { "text": "Add a README with setup instructions" },
    "model": { "id": "composer-2" },
    "repos": [{ "url": "https://github.com/your-org/repo", "startingRef": "main" }],
    "autoCreatePR": true
  }'

一条 curl 就能创建云端 Agent、让它干活、自动提 PR。Python、Go、Ruby 随便调。

和 Cursor IDE/CLI 的关系

把它们放在一起看就清楚了：

底层是同一个 Agent。区别只是入口不同——IDE 里按快捷键、终端里打命令、代码里调 API。

定价和限制

定价： SDK 运行遵循和 IDE/Cloud Agents 相同的定价、请求池和隐私模式。费用显示在团队的 Usage Dashboard 里，标记为 SDK。

API Key 类型： 支持用户级和 Service Account 级 Key。Team Admin Key 暂不支持。

已知限制（公测阶段）：
- 内联 MCP 服务器在 Agent.resume() 后不持久化，需要重新传入
- 本地 Agent 不支持 Artifact 下载（返回空列表）
- 工具调用的 schema（args、result）不稳定，应视为 unknown
- OAuth for local MCP 需要先在 Cursor App 里登录过

安装：

npm install @cursor/sdk

API Key 从 Cursor Dashboard → Integrations 获取。

Cursor SDK 做的事不复杂——把 IDE 里的 Agent 能力开放成 API。但这个"不复杂"的事情意义很大。AI 编程正在从"人用 AI 写代码"转向"系统用 AI 写代码"，Cursor SDK 是这个转变的基础设施。以后你的 CI 跑的不只是测试和 lint，还有一个 AI Agent 在做代码审查和自动修复。

作者: itech001
来源: 公众号：AI人工智能时代
主页: https://www.theaiera.cn，每日分享最前沿的AI新闻和技术。

本文首发于 AI人工智能时代，转载请注明出处。