Agent 不该住在设置页里（Cursor Agent SDK 和“把 agent 当成仓库”这件事）
Cursor 发布 Agent SDK：把 agent 写成一个文件夹，instructions、tools、skills、evals 都进仓库，用 eval 进 CI 来管住它。
你上一次改 agent 的提示词，是在哪儿改的？
如果答案是“某个后台的文本框”，那你大概也回答不了接下来的问题。
改之前它长什么样？
谁改的？
为什么改？
改完之后，它变好了还是变坏了？
这不是你一个人的问题。
过去这段时间，很多团队做 agent 的方式都差不多。在一个配置页里填一段提示词，勾几个工具，点保存。能跑，就算上线。
它看起来很快。
但它有一个代价，很少有人算。
你把一个会做决定的东西，放在了一个没有历史、没有评审、没有测试的地方。
10 月 26 日，Cursor 在 changelog 里发布了 Agent SDK。官方的说法是，你可以把一个 agent 定义成一个代码文件夹，用 eval 测它，再部署到 Cursor 或者你自己的基础设施上。
听起来像又一个开发工具。
我不这么看。
我觉得它真正改的，是 agent 的户口。
它把 agent 从“后台配置”迁到了“可以 review、可以版本化的项目文件夹”。
配置页的问题，不在配置页
我们先把默认做法拆开看。
一个 agent，大致由三样东西组成：
- 它被告诉了什么（提示词）
- 它能做什么（工具）
- 它做得对不对（评测）
在配置页模式里，这三样东西散落在三个地方。
提示词在文本框里。
工具在某个下拉菜单里。
评测呢？
多数时候不存在。靠的是“我试了几次，感觉还行”。
问题在于，感觉不是证据。
你不会接受一个同事不经 review 就把代码推进主干。
但你可能每天都在接受一个 agent 不经 review 就换了一种做事方式。
这就是默认的陷阱。
我们把 agent 当成一项设置，而不是一份软件。
如果 agent 是软件
那它就应该享受软件的全部待遇。
版本控制。
代码评审。
自动化测试。
部署流水线。
这些东西都不新。工程界花了很长时间，才把它们磨成常识。
Agent SDK 做的事情，说穿了，就是把 agent 塞回这套常识里。
换句话说，它没有发明新纪律。
它只是让 agent 也开始守旧纪律。
一个文件夹长什么样
按官方 changelog，起步只要一条命令：
npx @cursor/agent-sdk init ./my-bot
（顺手提醒一句：changelog 里的包名是 @cursor/agent-sdk，但截至 10 月 28 日，官方文档的安装和代码示例写的是 @grok/agent-sdk。两边对不上，本文命令照 changelog 写，动手前以你实际装到的包为准。）
然后跑 agent-sdk dev，在本地起一个 playground，先跟它聊几轮。
如果你不想从空白开始，可以加 --template。官方给的模板包括安全审查、owners 策略审批、PR 自动修复，以及 Linear 或 Jira 的工单分诊。
据官方文档，项目结构大致是这样。以下都在 bot/ 下面：
bot/instructions.md：必需，常驻的系统提示bot/tools/*.ts：一个文件一个带类型的工具bot/skills/：按需加载的流程bot/mcp-connections/：接进来的 MCP 工具bot/subagents/、bot/channels/、bot/hooks/、bot/schedules/
只有一个例外：
evals/：放在项目根目录，和bot/平级
写好以后，agent-sdk validate 校验，agent-sdk deploy 部署。部署到 Cursor 的话，官方说会给你一个 URL，密钥和集成在 Cursor 的控制台里管理。你也可以部署到自托管的基础设施上。
注意一个细节。
evals/ 和 bot/ 是平级的。
测试不是 agent 的附属品，而是和 agent 并排站着的东西。
这个摆放本身就是一个观点。
每个文件夹都是一根杠杆
我们一层一层看。
1) instructions 只写几行
文档的建议很克制。instructions 只写身份、什么时候用哪个工具、输出是什么格式。多步流程放进 skills。
这和很多人的直觉相反。
很多人以为提示词越长，agent 越听话。
但长提示词往往只是把“我还没想清楚”写得更长。
短 instructions 会逼你回答一个问题：这个 agent 到底是谁？
没有这个答案，agent 只会是一锅什么都往里放的汤。
2) 一个工具一个文件
bot/tools/ 里，一个文件就是一个带类型的工具。
这意味着每个工具都有自己的 diff、自己的评审记录、自己的修改历史。
你终于可以问：这个工具是谁加的，为什么加？
而不是对着一份越拉越长的工具清单发呆。
3) skills 是按需取用的经验
把多步流程放进 skills，本质上是把“怎么做事”从“我是谁”里拆出来。
身份常驻。
流程按需。
这是在给 agent 的注意力做减法。
4) channels 决定它在哪里醒来
据官方说法，agent 可以被这些事件叫醒：
- GitHub、GitLab、Bitbucket 上的 PR、评论、CI 事件
- Slack 里的 @ 和私信
- 任意 webhook
- cron 定时任务
而且每段对话对应一个 session。在同一个 PR 或同一个 Slack 线程里接着追问，续上的是同一个 session。
这一点容易被低估。
一个记得上一轮说过什么的审查 bot，和一个每次都从零开始的审查 bot，是两种东西。
5) evals 是它的成绩单
这是整个 SDK 里我最在意的部分。
按官方文档，一个 eval 会给真实的 agent 发一条固定的消息，然后断言它做了什么：
- 调用了哪些工具
- 工具的入参是什么
- 回复长什么样
你还可以接一个 judge 来打分。
agent-sdk eval --junit 可以把结果接进 CI。
agent-sdk github replay 可以把一个真实的 PR 变成签名的 webhook 回放，不用等下一次 push，就能测一个由 GitHub 事件驱动的 bot。
换句话说，你终于可以对 agent 说一句：交作业。
现在说点不那么好听的
任何工具都有它的边界。
这个也不例外。
1) eval 会真的跑工具
文档里写得很清楚，eval 不是模拟。它会真的调用工具。
如果你的工具会写数据库、发评论、改工单，那跑一次 eval，就真的写了一次。
文档给的办法，是在写操作之前判断 ctx.session.purpose === "eval"，把评测场景拦下来。
这不是可选项。
忘了这一步，你的测试本身就会变成一次事故。
2) “同一套 harness”是官方说法
官方称，Agent SDK 用的是驱动 Bugbot、Security Review、Approval Bot、Rollouts 的同一套 harness。
这句话值得记住。
但也要记住它的出处。这是 Cursor 自己说的，目前我没有看到第三方拆开验证过。
它能说明 Cursor 在自家产品上用过这套东西。
它不能自动说明你的 agent 也会一样好用。
3) 文件夹不会替你思考
把 agent 放进 Git，只是让坏决定变得可以追踪。
它不会让坏决定消失。
如果你的 eval 只测了最顺的那条路，它就只是一张好看的成绩单。
真正的转变，是你的位置
回到开头那个问题。
在配置页模式下，你是 agent 的操作员。你点按钮，调参数，看它跑。
在仓库模式下，你更像一个导演。
你写剧本，也就是 instructions。
你定分工，也就是 tools 和 skills。
你排场次，也就是 channels 和 schedules。
然后你用 eval 验收每一场戏。
操作员关心的是：它这次答对了没有？
导演关心的是：我怎么知道它下次也会答对？
后一个问题，只有当 agent 有历史、有测试、有评审的时候，才回答得了。
如果你想开始
我的建议很简单：
- 先用一个模板起步，别从一张白纸写起
- instructions 只留几行，写不下的东西挪进 skills
- 每加一个工具，就同时加一条 eval
- 任何会写数据的工具，先加上
ctx.session.purpose的判断 - 让 eval 进 CI，坏了就拦住合并
这些都不难。
难的是承认一件事。
agent 不是一个开关，它是一件需要维护的作品。
你怎么对待它的提示词，就是你怎么对待它的品味。
品味写不进配置页。
但它可以写进一个仓库，然后被一次又一次地 review。
来源：Cursor changelog；Agent SDK 文档；项目结构；Evals。命令与包名照 changelog 写作 @cursor/agent-sdk；截至 2026-10-28，官方文档的安装和代码示例写的是 @grok/agent-sdk，两者不一致；“与 Bugbot、Security Review 等同一套 harness”为官方说法，未见第三方验证；“操作员和导演”为作者看法。利益关系说明：本站日常使用 Cursor 和 Grok Bot。