一个智能体就是一个项目目录
Cursor 在 10月26日开放了 Agent SDK，官方说法很直白：这套东西就是他们自己做 Bugbot、Security Reviewer 与 Rollouts 的底座。在此之前，想做一个顺手的团队智能体，要么接受别人设计好的工作流，要么从零搭一遍接 GitHub、管密钥、防误操作的脚手架。
SDK 的核心机制是文件放哪就决定它是什么。项目根目录下，bot/instructions.md 是常驻提示词，用 Markdown 写；bot/agent.ts 里用 defineAgent 声明能用哪些工具、是否在沙箱里跑；tools/ 下每个 .ts 文件就是一个工具，文件名即工具名；channels/ 决定它从哪里被唤醒，比如 GitHub、Slack、webhook 或定时任务；evals/ 放评测用例。提示词、工具、评测全是仓库里的文件，可以走同一套审查与回滚流程。
五步跑通第一个智能体
第一步，备好 Node 22.13 以上版本。第二步，用 agent-sdk init 生成项目骨架，官方带四个模板：安全审查、CODEOWNERS 式策略审批、PR 自动修复、Linear 与 Jira 工单分派。第三步，改 instructions.md——模板里那份写得很克制，只报能被真正利用的漏洞，包括注入、越权、密钥泄露、反序列化、SSRF 与远程代码执行，明确不管代码风格，并要求模型只调用一次提交结论的工具、用结构化字段交付。
第四步，写工具。模板里的 post_findings 用 defineTool 加 zod 定义输入格式，严重程度、文件、行号、标题、说明一个都不能少；模型只能按这个 schema 交结果，真正往 GitHub 发评论的是工具里那段确定性代码。模板里还有个细节值得抄：开头先判断当前是不是评测会话，如果是就直接返回、不真的发评论，避免测试把真实仓库搞脏。
第五步，写 eval 再上线。eval 用例拿到固定输入，比如一段带 XSS 的 diff，然后断言三件事：任务成功、确实调用了 post_findings、回复里提到 XSS 或注入。也可以让另一个模型当裁判打分，还能把 eval 挂进 CI，每次提交自动跑一遍。
官方给的定位是：智能体的提示词、工具与评测都变成代码，于是它可以像普通软件一样被审查、被测试、被回滚，从调出来的助手变成写出来、测出来的系统。
部署的两条路与三条纪律
上线只要一条命令：agent-sdk deploy 会把智能体构建好、给一个 URL、跑在 Cursor 的基础设施上，密钥与集成在面板里管，本地和线上的日志、eval、playground 保持一致。不想把代码交出去也能自托管——每个智能体就是一个 Node 进程，可以打成容器跑在自己网络里。这一点对企业采购是硬门槛，数据位置与合规要求往往比功能更先决定选型。
落地时更该注意三件事。一是把 eval 当成回归测试而不是验收测试，改一次提示词就跑一遍，否则感觉变好了会成为唯一标准；二是给每个工具设权限边界，能读文件不等于能发评论，能发评论不等于能合 PR，确定性代码要挡在模型和外部世界之间；三是记住这套 SDK 不是开源的，用的是 Cursor 自家许可，敏感场景要先看清条款再决定托管还是自托管。
粤公网安备44130202001736号