Cursor开源Agent SDK：用文件夹就能造AI代理

AI编程工具Cursor推出Agent SDK，把内部构建AI代理的整套工具链开放给开发者。这不是简化版，而是Cursor团队日常用来构建代码审查、安全检测、变更审批等代理的同一套底层设施。用一句话概括它的理念：最好的AI代理不是用来聊天的，而是安安静静帮你写代码、查漏洞、审PR的那种。

Agent SDK到底是什么？

SDK听起来很技术，其实就是一个“零件包”。Cursor这次放出的零件包，专门用来搭AI代理。

代理和聊天机器人有本质区别。聊天机器人回答一个问题就停下，代理则接手一整件工作：拆解步骤、调用工具、推进到完成为止。它更像一个能真正干活儿的助手，而不是一个搜索框。

AI代理（AI Agent） 是相对于单轮问答式模型的一个范式转变。传统聊天模型接收输入、生成输出即结束；代理则被赋予目标、工具和执行循环，能自主决定下一步动作并持续迭代，直到任务完成或触发终止条件。技术上，代理通常由三部分构成：规划（把目标拆成子任务）、工具调用（执行外部动作，如读文件、发请求、查数据库）和记忆（保留上下文与中间结果）。业界常说的 ReAct、Plan-and-Execute 等模式，都是对这三者组织方式的不同设计。理解这一点很关键：代理的能力上限不只取决于底层模型，更取决于工具设计是否合理、指令是否清晰、循环控制是否稳健。

一个文件夹，两个文件

Cursor把代理的构建方式压缩到了极简程度：一个文件夹装两样东西。

**指令（Instructions）**是用Markdown写的纯文本，告诉代理要做什么、怎么做。你不需要写复杂配置，就像给新同事写工作交接笔记一样自然。

**工具（Tools）**是用TypeScript写的具体动作，是代理的“手”。指令是大脑，工具是手脚，两者放进同一个文件夹，这个文件夹就是你的代理。

这种设计的聪明之处在于：代理变成了可读、可版本控制、可回滚的普通代码资产，而不是一个你只能反复试探的黑箱。

底层管道Cursor替你跑

代理运行起来后，模型选择、指令解析、工具调用、循环推进这些脏活累活，全部由Cursor的运行时接管。你只需要提供想法和指令。

部署上给了两条路：托管在Cursor的基础设施上，零运维；或者跑在自己的机器上，拿全部控制权。

安全性方面也有默认兜底——密钥不会裸奔在代码里，代理运行在隔离环境中，不会越界访问不该碰的东西。

运行时（Runtime） 指的是代理从启动到结束期间，负责调度模型推理、解析指令、执行工具、管理上下文和控制循环的底层系统。自己搭建运行时通常要处理很多琐碎问题：上下文超长如何截断、工具调用失败如何重试、多步任务如何防止死循环、并发任务如何隔离资源。Cursor 把这一层封装起来，开发者只需声明"做什么"和"能调用什么"，无需关心调度细节。托管部署与自部署的区别主要在于数据流向和运维责任：托管省去服务器与升级维护，自部署则适合对数据驻留、合规审计有硬性要求的团队。

被低估的功能：内置评估

多数人会把注意力放在“怎么搭”上，但真正决定代理长期质量的是评估（Evals）。

每次修改指令或新增工具，你都可以跑一组测试来判断代理是变好了还是变差了。这让代理的迭代从“凭感觉”变成“看数据”。配合文件夹式的代码管理，你可以对比版本、回滚故障、持续打磨。

一个不跑评估的代理，可能在你不注意的时候悄悄退化。这个功能值得每个使用者认真对待。

评估（Evals） 是 AI 工程中用于量化系统表现的一套方法，类似于传统软件里的单元测试与回归测试。对代理而言，评估通常包含一组固定输入（如若干条代码变更、工单样本）和判定标准（输出是否包含关键信息、是否触发了正确的工具、是否越权操作）。由于大模型输出具有随机性，单次结果不足以说明问题，评估往往需要多次运行并统计通过率。没有评估，指令微调很容易变成"改一处、坏一处"的盲目试错；有了评估，每次改动都能得到可比较的分数，从而使代理的演进具备工程可控性。这也是当前 AI 应用从演示走向生产的关键环节。

代理能做什么：从PR审查到Slack助手

Cursor官方给的起步示例是PR审查代理：盯住新的代码变更，读完并留下有用的评论，像一个永不疲倦的队友。

其他典型场景包括：triage代理，新工单进来立刻分类、打标签、标记紧急项；Slack助手，回答团队反复问的那一百个问题，顺便处理小任务。

这些代理的共同点是：接手一件可重复的真实工作，并且因为你亲手写了指令，它的行为完全按你的意图来，而不是某个通用助手的“一刀切”风格。

上手建议与门槛

从小处开始。 别第一天就想搭一个大而全的代理。挑一件无聊、重复的小事，先让它跑通，再逐步扩展。

把时间花在指令上。 纯英文（或中文）描述那部分承担了大部分工作量。像给新同事做细致交接一样写指令，清晰的指令几乎总能打赢聪明的代码。

认真跑评估。 测试听起来无聊，但它是代理持续变好而非悄悄变糟的分水岭。

需要坦白的是，这套工具比点选式产品更动手。如果你从没碰过代码，会遇到文本文件和一点TypeScript的学习曲线。但它也意味着你不被锁死在别人的代理能力边界里。如果你只想要一个能对话的机器人，Cursor的Grokbot是零代码路线；如果你想要一个团队能测试、能信任、能长期依赖的代理，Agent SDK才是对的那个工具。

TypeScript 是微软主导开发的一门静态类型语言，是 JavaScript 的超集，编译后可运行在 Node.js 等环境中。它在保留 JavaScript 灵活语法的同时加入了类型标注，能在编写阶段发现参数类型不匹配等错误，因此在工具链、后端服务和 AI SDK 生态中被广泛采用。对初学者而言，只需掌握函数定义、对象结构和类型声明这几项基础，就足以编写代理的"工具"部分；复杂的类型体操并非必需。相比从零学习一门新语言，这里的门槛主要体现在"读懂并修改现成代码"，而非独立从零构建。

工具平权的信号

过去构建一个真正能用的代理，需要一整个团队和大量时间。现在需要的是一个文件夹、清晰的指令和一点折腾的耐心。Cursor把内部系统原样开门，意味着个人开发者和小团队第一次拿到了和大型组织同等级别的代理构建能力。

这种能力有复利效应：每搭一个小代理，下一个会更快。而眼下大多数人还没意识到这扇门已经打开——这个窗口期不会一直存在。