先说一个具体的事：Cursor 内部有个团队攒了一堆「踩过的坑」笔记。他们做了个叫 kb-reviewer 的智能体，每次有人提 PR，它就去比对这次改动有没有推翻某条旧结论，并且指出是哪一条笔记。
这个智能体，他们做了大约一天。
它现在跑在主代码库的每一个 PR 上。能让它稳定跑起来的东西，就是这次开放的 Agent SDK。
时间线有点乱，先说清
Cursor 在官方博客发文，署名 Rustam Lalkaka，标题直接写「generally available」。博文署的日期是十月二十日，而中文媒体大多在十月二十六、二十七日报道——北京时间二十七日凌晨，官方在 X 上正式宣布开放。
三个日期差了一周，各家写法不一。要引用时间，用「十月下旬」最稳。
还有一处更要留意的口径冲突：四月二十九日 Cursor 发过一个公开测试版，包名是 @cursor/sdk，按 token 计费；这次换成 @cursor/agent-sdk，官方没有任何一页解释这两个包是什么关系。也有报道把它写成 @grok/agent-sdk，与官方博文示例代码里的 import 对不上。
这不是改名那么简单，这是升级路径没说清。 如果你夏天就在用旧包，迁移前先去官方文档确认，别默认它只是换了个名字。
一个智能体，就是一个文件夹
这是整套设计里最值钱的一句话：文件放在哪，决定它是什么。
bot/instructions.md：常驻的系统提示词，必需项bot/tools/*.ts：一个文件一个工具，工具名就是文件名，参数有类型bot/skills/：按需加载的流程说明，不用全塞进系统提示bot/subagents/：可以派活的子智能体，各有各的工具和会话bot/channels/：它从哪里被唤醒——GitHub、GitLab、Bitbucket 的 PR 事件，Slack 消息，自定义 webhook，定时任务bot/hooks/：只观察、不改流程的事件订阅evals/*.eval.ts：评测用例
defineAgent 里写几行配置：名字、模型 id、参数（比如 effort、fast）、本地工作目录。剩下的事——模型循环、工具调用、会话、沙箱、密钥、部署——平台管。
做过智能体的人都熟悉另一条路：提示词散在后台配置页，工具函数在代码里现拼，上线之后改一个字都得靠截图和记忆回滚。文件夹方案把这套东西拉进了版本控制。
提示词变文档，工具变函数，这两刀切得准
提示词写成 Markdown，最大的好处不是技术上的，是组织上的：产品经理和工程师可以对着同一个文件讨论，而不是一个人看配置页、一个人看代码。
工具写成 TypeScript，好处是类型和编辑器补全。已经写前端或 Node 的团队几乎零学习成本——bot/tools/ 下丢一个导出函数的 .ts 文件，它就是一个工具。
这在工程上有个被低估的副作用：工具的入参出参一旦有类型，评测用例就有了断言的抓手。 没有类型的时候，你只能比对最终那段文字像不像；有了类型，你可以直接断言「这个工具被调用了、参数是这几个字段」。
evals 才是这次的主角
大多数智能体团队的真正痛点不是做不出来，是做出来之后不敢改。
换个模型，改一句提示词，质量是升是降？没人知道。于是大家的选择是「能跑就别动」。
Agent SDK 把评测做成了默认项：项目里放 evals/*.eval.ts，改完跑一遍，回归测试挡在部署前面。配套还有事件回放——某次运行失败了，可以把当时的事件序列重放一遍，看它到底在哪一步拐错了弯。
官方给的 agent-sdk eval 命令就是干这个的。用官方原话说，先跑通一轮再谈优化。
顺带说一句，这套思路站内早就讨论过：微软把几百次智能体会话总结成九类翻车模式，核心结论是「能编译的代码不代表是对的」；OpenAI Agents SDK 的中文上手讲的也是从接口调用走到可观测。Cursor 这次的不同在于，它把评测放进了脚手架，而不是留给你自己搭。
部署两条路，差别在合规不在技术
搞定了就一条命令：agent-sdk deploy。它从当前 Git ref 构建、分配一个 URL、跑在 Cursor 的基础设施上；密钥和第三方集成在后台面板管，日志、评测、演练场本地和线上一致。
另一条路是自己跑。每个智能体就是一个 Node 进程，打成容器丢进 Kubernetes 或 ECS 都行，不需要特殊依赖。Node 版本要求不低，四月测试版的口径是 22.13 以上。
这条路的真正意义在采购环节：用 Privacy Mode 的团队可以直接用托管；还在旧版隐私模式上的团队，官方要求必须自托管。
真上手，四条命令
第一，建目录，装包，写 bot/instructions.md。第二，agent-sdk validate 校验项目结构。第三，agent-sdk tool call 单独调一个工具，确认它返回的真是你要的证据——这一步很多人跳过，然后在联调时怀疑模型。第四，agent-sdk run 跑一轮真实对话，把打印出来的会话轨迹读一遍。最后 agent-sdk eval 跑冒烟评测。
官方说只有 run 和 eval 需要 Cursor 凭证，其余离线可做。
不想从零写，还有五个模板：安全审查、PR 自动修复、按 CODEOWNERS 路由评审人、Linear 工单分诊、Jira 工单分诊。模板只是起点，指令、工具、MCP 连接、触发事件都能改。
代价清单，四条得先知道
一，定价是空白。 官方博文没写价格、没写限额、没写许可。四月那版是按 token 计费，这次一个字没提。托管路线要花多少钱，是动手之前第一个该问的问题。
二，许可不是开源。 包以 npm 形式发，许可证写的是 Cursor 自家的 SDK 许可。想 fork 改造、想嵌进对外销售的产品，先看条款。有第三方指南提到，对外销售需要单独和 Cursor 谈商务。
三，文档自己承认的坑。 工具调用的 schema 还不稳定；内联的 MCP 服务器配置不随会话恢复而存活；本地运行时通过用户级配置加载的、需要 OAuth 的 HTTP MCP 服务器（比如 Notion、Linear）可能加载不上，得走云端运行时绕。
四，绑定的是它的路线图。 默认示例用的是自家模型 id，托管默认落在自家基础设施上。你要的是「随便换模型、随便换云」，这套不是为那个设计的。
它和另外两条路怎么分工
站内最近写过两个相邻的东西，容易混，这里切开说。
Vercel 的 durable-harness解决的是「跑到一半崩了怎么办」——它不管你用什么框架，给你一层断点续跑。这是运行时层面的补丁。
Cursor Agent SDK 解决的是「这个智能体怎么像软件一样被维护」——目录结构、评测、部署流水线。这是工程流程层面的方案。
把智能体接到编辑器里那条路（JetBrains 那类做法）解决的是「我不想被一家模型绑死」——编辑器当宿主，谁家的智能体都能接进来。这是入口层面的开放。
三条路不冲突，甚至可以叠：入口用编辑器，流程用 SDK，跑起来加一层持久化。
至于 Cursor 的 Projects，那是产品功能，一个协调者指挥一堆子智能体；Agent SDK 是给开发者的底座，两者不是一个层级的东西。
对三种人，值不值得动
已经用 Cursor 的团队： 值得试，尤其是那些已经把内部自动化写成脚本的。把它们搬进 bot/tools/，换来的是评审、版本和评测三件套。
重度自建智能体的团队： 先问自己一个问题——你的智能体跑在谁的云上，能不能出内网。能出，这套省事；不能出，走容器路线，但要想清楚 SDK 的默认假设都是绑着 Cursor 的。
个人开发者和小团队： 观望更划算。定价没公布、包名刚换、schema 还不稳，这三条加起来意味着现在上车要承担迁移成本。先用持久化运行时那类轻量方案把流程跑通，等价格明牌再说。
老达点评
一、这次卖的不是功能，是一种工程习惯。 智能体行业这两年最大的浪费，是每个人都在重新发明「怎么知道它变差了」。把评测写进脚手架，等于把这个习惯变成默认值。默认值的力量，比任何功能都大。
二、文件夹这个隐喻选得好，好到不用解释。 目录结构本身就是文档：instructions 是它记得什么，tools 是它能干什么，channels 是它什么时候醒，evals 是怎么证明它没退步。四个问题答完，一个智能体就定义清楚了。
三、定价空白这件事，比看起来严重。 四月按 token 收，十月不提价格，这种沉默通常意味着两种可能：还在算，或者打算按用量悄悄收。团队做预算时，先把最坏情况算进去——按编辑器用量池的几倍估。
四、包名从 @cursor/sdk 换到 @cursor/agent-sdk 却不解释，是个信号。 它说明这两个东西在官方心里不是同一个产品线。老用户别赌它是改名，去读文档。
五、别把 SDK 当成「不用学工程」的借口。 它降低的是脚手架成本，不是判断成本。评测用例写什么、什么算通过、什么该拦下来，这些还得你自己想。工具能给你一条流水线，给不了你标准。
想把这条线看全，AI 编程工具专题里从编辑器到 CLI 到 SDK 都有；如果你更关心智能体怎么接进日常工作流，AI 智能体与自动化专题更对路。
