Cursor SDK：用写代码的方式写 Agent

Cursor 发布了 TypeScript SDK，让你用几行代码就能调用和 Cursor 编辑器相同的 Agent 运行时。这不是又一个 Agent 框架，是 Cursor 把自己的核心引擎开放成了基础设施。本文拆解它的设计逻辑、三种运行时架构、和 Claude Code 的关键差异。

4 月 29 日，Cursor 发了一条推文，announcing 了 Cursor SDK。35 秒的视频，7333 个赞，4101 个书签。

书签和点赞的比例高得离谱------56%。这说明一件事：开发者不只是觉得"挺酷"，而是真的打算回头用。

视频来源：x.com/cursor_ai/s...

官方推文就一句话：

We're introducing the Cursor SDK so you can build agents with the same runtime, harness, and models that power Cursor. Run agents from CI/CD pipelines, create automations for end-to-end workflows, or embed agents directly inside your products.

三个关键词：CI/CD 流水线、端到端工作流自动化、嵌入产品。这不是在说"又一个 Agent 框架"，这是在说------Cursor 把自己从"编辑器里的工具"升级成了"可编程的基础设施"。

距离 GPT-5.4 发布只隔了六周，Cursor 就交出了这个答卷。文章发布这几天，SDK 已经迭代了 6 个版本（最新 1.0.12），Cloud Agent API 升级到了 v1，Cursor 还陆续推出了安全审查、企业模型管控、消费预警等配套功能。我把最新进展也一起更新进来了。

一. 它到底是什么？

用最简单的话说：Cursor SDK 让你用 TypeScript 代码调用和 Cursor 编辑器完全相同的 Agent 引擎。

不是"类似"的引擎，是"同一个"。你在 Cursor 编辑器里用的那些能力------代码库索引、语义搜索、MCP 服务器、Skills、Hooks、Subagents------SDK 全部开放了出来。

最简的用法只有四行：

typescript 复制代码

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

npm install @cursor/sdk，拿到 API Key，就能跑。

但"能用"和"好用"是两回事。Cursor SDK 真正的差异化，在于它的三种运行时架构。

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

这是 Cursor SDK 最核心的设计决策------Agent 不是只能在你本机跑的。

Local 本地运行： Agent 跑在你的 Node 进程里，直接访问本地文件系统。适合开发脚本、CI 检查等场景。你写几行代码，它就在你的项目目录里干活，跟你自己在终端里用 Cursor 一样。

Cloud 云端托管： Agent 跑在 Cursor 提供的专用 VM 上。每个 Agent 拿到一个克隆的仓库副本、一个完整配置的开发环境。你的电脑合上盖子、断网了，Agent 继续跑。跑完了还能自动创建 PR、推送分支、附带截图和 demo。

typescript 复制代码

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

注意这段代码的关键设计：发完任务就走了，回头再来拿结果。 这是真正的异步 Agent，不是等你盯着看的聊天窗口。

Self-hosted 自托管： 和云端托管一样的形态，但 VM 跑在你自己的基础设施上。代码不出你的网络，工具执行不出你的边界。

C3 AI 的高级总监 Amir Delgoshaie 说了句话我觉得很有代表性："The Cursor SDK gives us control over where these programmatic agents run and which models they call, which is critical for our customers with strict governance and security requirements." 他们一天之内就在自己的基础设施上跑起了 SDK，完全定制化。

三种运行时共享同一个底层框架，代码几乎不用改------换个配置字段，就能从本地切到云端，或者切到自托管。这对工程团队来说太重要了。你在本地调试好了，推到生产环境只需要改一行配置。

三. 不只是"调 API"，是完整的 Agent 运行时框架

很多人可能会想：这不就是一个封装了 Cursor API 的 SDK 吗？不是。

SDK 提供的是完整的 Cursor Runtime Framework------和 Cursor 桌面端、CLI、Web 端用的是同一套引擎。包括：

代码库索引和语义搜索： Agent 不是"盲人摸象"，它能索引整个代码库，做语义搜索和即时 grep。这是你自己从零搭一个 Agent 很难做到的部分------索引的构建、增量更新、检索效率，每一个都是工程难题。

MCP 服务器： Agent 可以通过 stdio 或 HTTP 连接外部工具和数据源，配置方式和你平时在 Cursor 里用的 .cursor/mcp.json 一样，也可以在代码里 inline 传入。

Skills： Agent 自动加载仓库 .cursor/skills/ 目录下的技能。你之前在 Cursor 里积累的 Skills，SDK 直接复用。

Hooks： 通过 .cursor/hooks.json 观察、控制、扩展 Agent 循环。在云端、自托管、本地三种环境下都能用。

Subagents： 主 Agent 可以通过 Agent 工具把子任务委派给命名的子 Agent，每个子 Agent 有自己的 prompt 和模型。这是做复杂工作流的关键能力------不是一个大 Agent 包揽所有事，而是按需分派。

把这些能力加在一起，Cursor SDK 不只是在"调用一个模型"，而是在"运行一个完整的 Agent 工作流"。区别很大。调模型你只需要一个 API endpoint，运行工作流你需要状态管理、上下文维护、工具编排、错误恢复------这些才是真正的工程复杂度所在。

四. Composer 2：专门为编码打造的模型------现在有了技术报告

官方博客特别推了 Composer 2 这个模型：

Composer 2 is a specialized coding model that achieves frontier-level performance at a fraction of the cost of general-purpose models.

"前沿水平的性能，通用模型的一小部分成本。"

3 月 27 日，Cursor 发布了 Composer 2 技术报告，揭了底：Composer 2 基于 Kimi K2.5 的 MoE 架构，训练分两阶段------代码持续预训练 + 大规模 RL（在真实 Cursor 会话中训练）。关键 benchmark 数字：

Benchmark	分数
CursorBench	61.3（比 Composer 1.5 提升 37%）
SWE-bench Multilingual	73.7
Terminal-Bench	61.7

Cursor 把它描述为"Pareto-optimal tradeoff between accuracy and cost for interactive developer workflows"------在准确率和成本之间找到了最优平衡点。逻辑上说得通------通用模型要啥都会，编码模型只需要把代码写好。能力范围窄了，效率就可以上去。Composer 2 还支持 thinking 参数，可设为 "low" 或 "high"，在推理深度上做调节。

SDK 里切换模型只需要改一个字段：

typescript 复制代码

// 用 Composer 2
model: { id: "composer-2" }

// 用 GPT-5.5
model: { id: "gpt-5.5" }

同一个 Agent、同一套工具链、同一种运行时，换个模型就完事了。这让"用便宜模型跑简单任务、用贵模型跑复杂任务"变成了一种配置策略，而不是架构决策。

值得一提的还有 Cursor 的 Agent Harness 适配。4 月 30 日官方博客"Continually improving our agent harness"透露了一个细节：不同模型在编辑文件时的行为不一样------OpenAI 的模型训练用 patch-based 格式编辑文件，Anthropic 的模型训练用 string replacement。Cursor 的 Harness 会根据模型自动切换编辑策略。这意味着你在 SDK 里换模型时，不只是换了推理引擎，连工具调用的适配也自动跟上了。

五. 谁在用它？做什么？

官方博客给了四个客户案例，每个都指向不同的使用模式。

Faire （George Jacob，高级工程经理）：用 SDK 在 Cursor 的云端运行时上跑程序化 Agent，不需要自己管 VM 和内存约束。关键词是并行运行------多个 Agent 同时跑，自动维护代码库健康。

Rippling （Tim Fall，高级员工软件工程师）：在 SDK 上构建 Slack 机器人、客服自动化、内部后台 Agent 的线束（harness）。关键词是嵌入产品------Agent 不是独立工具，是产品的一部分。

Notion （Quan Nguyen，软件工程师，开发平台）："工程师可以在 Notion 中记录一个 bug，将其交给 Cursor，然后在不离开页面的情况下获得一个已审查的 PR。" 关键词是端到端自动化------从记录问题到获得 PR，全程不需要切换上下文。

C3 AI （Amir Delgoshaie，高级总监，数据科学）：一天内在自有基础设施上跑起 SDK，完全定制化。关键词是自托管------代码和模型调用必须留在自己的环境里。

这四个案例基本上覆盖了 Cursor SDK 的三种核心使用场景：CI/CD 触发的程序化 Agent、端到端工作流自动化、嵌入产品的 Agent 体验。

官方还在 GitHub 上放了四个示例项目（github.com/cursor/cookbook），star 已经超过 2100：

Quickstart --- 最小 Node.js 示例，创建本地 Agent，发送一个 prompt，流式接收响应
Prototyping Tool --- Web 应用，在沙盒云端环境里快速搭建和迭代新项目
Kanban Board --- 看板工具，拖拽卡片让 Agent 接管任务，自动创建 PR
Coding Agent CLI --- 从终端启动 Cursor Agent 的命令行工具

六. 和 Claude Code 比，差异在哪？

这是很多人会问的问题。我用一个表格说清楚：

维度	Cursor SDK	Claude Code
接入方式	TypeScript SDK	CLI + API
运行时	Local / Cloud / Self-hosted 三种	仅本地运行
模型支持	OpenAI / Anthropic / Google / Composer 2 / xAI 等	仅 Anthropic 模型
云执行	内置专用 VM，仓库自动克隆	无内置，需自己搭基础设施
自动创建 PR	内置 `autoCreatePR`	手动
MCP 支持	完整（inline + 文件配置）	完整
Subagents	内置命名子 Agent	工具委派
Hooks	文件级 `.cursor/hooks.json`	无内置
状态	Public Beta	GA

截至 5 月初，Cursor SDK 支持的模型列表已经相当丰富：Claude 4.6 Opus、Claude 4.7 Opus、GPT-5.5、Gemini 3 Pro、Grok 4.20、Kimi K2.5，以及自家的 Composer 1/1.5/2。你可以在代码里用 Cursor.models.list() 动态获取当前账号可用的所有模型 ID。

核心差异就两个词：运行时 和模型。

Claude Code 是 Anthropic 的产品，只跑 Anthropic 的模型，只跑在你本机。你要云端执行？自己搭。你要多模型切换？没门。

Cursor SDK 是 Cursor 的产品，跑所有主流模型，跑在三种环境。你要云端？我给你 VM。你要自托管？你跑自己的基础设施。你要换模型？改一个字段。而且不同模型的 Harness 适配是自动的------OpenAI 模型用 patch-based 编辑，Anthropic 模型用 string replacement，SDK 自动切换，不需要你操心。

这不是说 Claude Code 不好------作为 Anthropic 的官方工具，它在 Anthropic 模型上的深度优化是 Cursor 做不到的。但如果你要的是可编程的 Agent 基础设施 而不是交互式编码助手，Cursor SDK 的设计明显更偏向那个方向。

说白了，Claude Code 是一个更好的"AI 编码助手"，Cursor SDK 是一个"Agent 运行时平台"。

七. 定价和可用性

当前状态：Public Beta，所有用户可用。官方文档明确写道："The TypeScript SDK is in public beta. APIs may change before general availability." GA 时间表未公布。

定价是标准的 token 消费计费------和你在 Cursor 编辑器里用 Cloud Agent 的价格一样，消耗出现在团队 Dashboard 的 "SDK" 标签下。没有单独的 SDK 计费层。Auto + Composer 的定价：输入 + 缓存写入 <math xmlns="http://www.w3.org/1998/Math/MathML"> 1.25 / 1 M t o k e n s ，输出 1.25/1M tokens，输出 </math>1.25/1Mtokens，输出6.00/1M tokens，缓存读取 $0.25/1M tokens。

API Key 从 Cursor Dashboard 的 Integrations 页面创建，支持用户 Key 和 Service Account Key。

npm 包 @cursor/sdk 发布后一周内已迭代 6 个版本（1.0.7 → 1.0.12），迭代速度说明团队在快速修复 bug 和打磨 API。

已知限制（官方文档记录）：

inline mcpServers 不会在 Agent.resume() 时持久化------每次需要重新传入
Artifact 操作对本地 Agent 不可用
local.settingSources 不适用于云端 Agent------云端总是加载项目/团队/插件配置
Hooks 只支持文件配置，不支持编程式回调
工具调用的 args 和 result 载荷不稳定------应视为 unknown
本地 SDK 无法触发 MCP OAuth 登录流程------只能复用之前在 Cursor 应用中登录的 token

八. 配套生态：不只是 SDK，是一整套企业级方案

SDK 不是孤立发布的。最近一周，Cursor 围绕企业场景密集推出了配套功能：

Cloud Agent API v1（4 月 29 日随 SDK 一同发布）：重大架构升级------Agent 和 Run 分离，Durable Agent 可以跨多个 Run 持久化存在，支持 follow-up prompt；SSE 流式推送 7 种事件类型（status、assistant、thinking、tool_call、heartbeat、result、error、done），支持断线续传；Agent 生命周期管理（归档、解归档、永久删除）；标准化 v1 响应/错误格式；17 个 API 端点覆盖 agents、runs、artifacts、worker tokens、metadata。Webhooks 标注"coming soon"。

Cursor Security Review（4 月 30 日）：Beta 状态，两个 always-on 安全 Agent，面向 Teams 和 Enterprise 计划。代码安全审查从"手动触发"变成了"持续运行"。

企业模型管控 + 消费预警（5 月 4 日）：企业管理员可以控制团队可用模型范围，设置软消费上限和智能预警。使用分析面板增加了 SDK 维度的拆分------你能看到 SDK 调用花了多少钱、跑了多少 token。

Bugbot 升级（4 月 8 日）：Bugbot 学会了 rules 和 MCP 支持，解决率到了 78%。虽然不是 SDK 直接功能，但说明 Cursor 在 Agent 自动化方向上持续投入。

这些功能加在一起，构成了一个从"SDK 接入 → 云端执行 → 安全审查 → 消费管控"的完整企业级闭环。如果你是 CTO 或工程 VP，评估的不只是"能不能用"，而是"能不能管"------Cursor 显然在针对这个决策路径做产品。

九. 我的判断

Cursor SDK 传递了一个很清晰的信号：编码 Agent 正在从"开发者的交互工具"进化为"组织的可编程基础设施"。

官方博客的原话是：

Coding agents are evolving from interactive tools for individual developers to programmatic infrastructure for organizations.

这不是在说愿景，这是在描述正在发生的事。Faire 在并行跑 Agent 维护代码库，Notion 在产品里嵌入 Agent 从 bug 到 PR 全自动，C3 AI 在自己的基础设施上一天之内就定制化部署------这些都不是"未来趋势"，是"现在的使用方式"。

而且这一周以来的配套功能发布节奏也印证了这一点------Security Review、企业模型管控、消费预警、Cloud Agent API v1，这些都不是面向个人开发者的功能，是面向组织的管控需求。

但我也有几个不确定的地方。

第一，Public Beta 意味着 API 可能变。一周 6 个版本迭代说明团队在快速调整，也说明接口还没稳定。你现在基于 SDK 搭的系统，可能需要跟着改。这是早期采用者的代价。已知限制也不少------inline MCP 不持久化、Artifact 对本地 Agent 不可用、Hooks 只支持文件配置不支持编程式回调------这些在实际工程中都会遇到。

第二，Composer 2 技术报告已经出来了，benchmark 数字看起来不错，但独立第三方的复现验证还没有。"前沿水平性能、低成本"的说法还需要更多实践来验证。

第三，SDK 目前只支持 TypeScript。官方还没给出其他语言的时间表。如果你是 Python 技术栈，暂时还得等。而且 Cursor 的 GitHub 组织（getcursor）目前没有公开仓库------没有 cookbook、没有示例项目、没有 issue tracker，社区生态还在很早期。

不过方向我认。把 Agent 从"工具"变成"基础设施"，这个思路和 Kubernetes 把容器从"运行方式"变成"编排平台"是同一个逻辑。工具解决的是个人效率问题，基础设施解决的是组织效率问题。Cursor SDK 瞄准的是后者。

从 Cursor 3 的"为所有代码都由 Agent 编写的世界而构建"，到 SDK 的"用代码写 Agent"，Cursor 在画一条很连贯的线：编辑器是 Agent 的交互入口，SDK 是 Agent 的程序化入口，两种方式共享同一个运行时。

一条线穿下来，野心不小。

参考资料

Build Programmatic Agents with the Cursor SDK --- cursor.com/blog/build-...
Cursor SDK Documentation --- cursor.com/docs/sdk/ty...
Cursor SDK Changelog --- cursor.com/changelog/s...
Official Announcement Tweet --- x.com/cursor_ai/s...
Composer 2 Technical Report --- cursor.com/blog/compos...
Continually Improving Our Agent Harness --- cursor.com/blog/contin...
Cursor Models & Pricing --- cursor.com/docs/models...
Cloud Agent API v1 Endpoints --- cursor.com/docs/cloud-...
Cursor Changelog --- cursor.com/changelog
npm: @cursor/sdk --- www.npmjs.com/package/@cu...

话题标签：#CursorSDK #AIAgent #TypeScript #编码Agent #Cursor