Cursor SDK 的自定义存储、自定义工具和 Auto-review
我们在 TypeScript 和 Python SDK 中推出了一批新功能。您现在可以选择以何种方式持久化智能体和运行元数据,将您自己的函数作为工具提供给智能体,通过 Auto-review 处理本地工具调用,并将子智能体嵌套到任意深度。此次发布还带来了一系列可靠性、性能和平台修复,让本地和云端 SDK 智能体更容易在生产脚本、CI 和自定义集成中运行。
自定义工具
您现在可以通过 local.customTools 传入函数定义,把自己的工具交给本地智能体使用;既可以在 Agent.create() 上设置,也可以针对每次 send() 单独设置。SDK 会通过一个名为 custom-user-tools 的内置 MCP 服务器,将这些工具提供给智能体,因此模型会通过与其他任何 MCP 工具相同的路径和权限门控来调用您的代码。
在此之前,要开放自定义能力,您需要自行搭建 stdio 或远程 HTTP MCP 服务器,并将其接入智能体。现在,只需一个函数定义就够了。自定义工具也会对父智能体的每个子智能体可见,因此工具定义一次,整个运行过程中都能使用。
Auto-review
默认情况下,本地 SDK 智能体会直接运行工具调用而不请求批准,因为在无头运行中没有人工参与。请将 local.autoReview 设置为改用 auto-review 处理这些调用。这样不会完全绕过审查,而是由分类器决定哪些调用自动运行,哪些需要暂缓。
您可以在 permissions.json 中使用自然语言指令来引导这个分类器。autoRun.allow_instructions 字段用于描述更倾向于允许的调用模式,autoRun.block_instructions 则用于描述需要保留以供审查的调用模式。比如,您可以允许对构建产物进行只读检查,同时始终在删除等破坏性操作上暂停。
{
"autoRun": {
"allow_instructions": [
"Read-only inspections of build artifacts under ./dist are fine."
],
"block_instructions": [
"Always pause delete operations so I get a chance to review them."
]
}
}JSONL 和自定义存储
两个 SDK 都会持久化智能体和运行元数据,以便您在进程重启后恢复智能体。此前,该存储一直使用 SQLite。现在,您也可以选择改用 JSONL 存储,它会写入一个纯文本的仅追加文件,您可以读取、比较差异,并提交到版本控制。SqliteLocalAgentStore 和 JsonlLocalAgentStore 也都可以直接导出。
如果这两种默认选项都不适合您的配置,请实现公开的 LocalAgentStore 接口,并通过 local.store 传入。您可以为临时性的 CI 运行构建内存存储,或者在希望智能体状态与应用程序的其他数据一同持久保存时,使用 Postgres 作为持久化后端。Python SDK 通过 bridge 暴露 host、JSONL 和组合式 JSONL 存储。
嵌套子智能体
子智能体现在也可以再创建自己的子智能体,层层嵌套。审查子智能体可以委派给测试编写子智能体,后者还可以继续向下委派,并且每一层都保留各自的提示和模型。无需手动开启任何功能;子智能体会话会注册其调用 Task 所需的执行者,因此只要智能体定义了子智能体,嵌套就会自动生效。
可靠性、性能与平台改进
此次发布还包含了一批面向两个 SDK 的体验优化和修复。
- 运行关联:现在每次
send()都会携带一个由平台生成的requestId``,并会在Run和RunResult中暴露,同时持久化到内存、SQLite 和 JSONL 存储中。您可以将脚本或 CI 运行与后端日志、分析数据和支持线程对应起来,无需再根据agentId` 推断。 - 本地运行中更可靠的
wait():本地运行不会再在终端结果写入前就提前结束wait()。Hydration 会持续刷新,直到运行进入最终状态,因此自动化流程读取到的结果是完整的。 - dispose 时更安全的检查点:释放本地智能体时,如果根引用缺失但检查点 blob 仍然存在,将不再删除检查点数据。只有在确实没有任何需要保留的内容时,才会清空智能体目录。
- 基于 HTTP/1.1 的云端流式传输:云端智能体会话现在能够在某些代理、较旧的 Node fetch 栈以及特定 CI 镜像使用的 HTTP/1.1 传输上正确进行流式传输。HTTP/2 的行为保持不变。
- 更轻量的导入:导入
@cursor/sdk时,不会再急切加载完整的本地智能体栈。仅使用云端功能或仅使用类型的场景,会在首次进行本地调用前跳过本地运行时开销,且无需改动 API。首次本地调用只会承担一次性导入成本,之后会保持缓存。 - 自包含的 TypeScript 类型:发布的
.d.ts文件不再引用未发布的工作区包。这修复了在skipLibCheck: false下出现的TS2305和TS2307错误,以及TurnEndedUpdate等流类型被静默视为any的问题。 - 内置 ripgrep:本地 shell 运行会使用随包提供的平台
rg二进制文件,而不会修改您的全局PATH。在 Windows 上,预置 ripgrep 也不会再覆盖Path变量。
- Composer 2 自动路由到 Composer 2.5:仍固定使用已退役
composer-2slug 的 SDK 客户端,现在会自动路由到 Composer 2.5,同时保留快速变体,因此旧脚本也能继续运行。
- 工作区作用域的
list_runs:Client、AsyncClient和Agent.list_runs现在支持可选的cwd,bridge 会回退到其启动时的工作区。当 bridge 作为子进程运行时,这修复了误报“agent not found”结果的问题。 - 更清晰的未找到错误:查找不在已解析工作区中的智能体时,现在会返回明确的未找到错误,而不是含糊的内部错误。
- 0.1.6 发布与分析:
cursor-sdk0.1.6 记录了 Buildkite 发布路径,并将 SDK 使用标记为sdk-python-,以便获得更清晰的分析数据。
运行 npm install @cursor/sdk 或 pip install cursor-sdk 即可升级。固定使用 composer-2 的脚本会自动迁移到 Composer 2.5,而 requestId 也可以安全地加入您的运行元数据 schema。完整详情请参阅 TypeScript 和 Python 文档。
画布设计模式与上下文用量报告
借助画布,智能体可以创建可与团队共享的交互式内容,例如仪表盘、报告和内部工具。
此版本引入了设计模式,以便更快地编辑画布,并提供了帮助您了解上下文用量的新方式,以及其他体验优化。
画布中的设计模式
画布现已提供设计模式。
您可以直接在画布中选择并标注 UI 元素,像在浏览器中一样引导 Cursor 进行编辑。无需再用文字描述更改,您可以直接指出要改的地方、提供反馈,并更快地迭代。
在画布中查看上下文用量报告
Cursor 现在可以在画布中显示您的智能体的上下文用量交互式报告。
上下文探索器会细分展示 token 在系统提示、工具定义、规则、技能等部分的使用情况。由于它是一个画布,您可以向智能体提出后续问题,它还可以自定义这份报告来回答您的具体问题。
点击画布中嵌入的 Debug with Agent 按钮,在新对话中请求 Cursor 帮您找出减少上下文用量的机会。
- 共享画布现在可以在浏览器中全屏打开,更方便向他人展示。
- 新增了让智能体在画布中嵌入按钮的能力,点击后会运行特定提示。
- 提升了智能体修复画布类型错误的能力。
- 改进了组件样式,并新增了更多图表自定义功能。
Cursor 企业版组织
企业客户现在可以在统一位置管理多个 Cursor 团队,并为每个团队设置不同的安全、治理、预算和功能控制。这些功能现已正式向所有企业客户开放。


组织
组织是承载您公司身份、管理和成员体系的顶层容器。它让管理员可以在一个地方查看和管理整个 Cursor 设置,包括所有团队的支出和 token 用量汇总。
团队
团队是部门、区域或子公司的运作单元。这也是管理员当前在其 Cursor 组织中管理的单位。我们已将这一单元置于组织之下,因此您可以管理多个团队,且每个团队都拥有各自的安全、治理、支出和功能设置。
一个用户可以属于多个团队,并在每个团队中担任不同的角色。对于现有客户,您现有的团队会被保留,并成为登录、路由以及创建新团队时的默认归属团队。
群组
群组是用户的轻量级集合,可跨团队使用,也可在团队内部使用。借助群组,你可以为特定用户群体单独设置模型访问权限、支出限额和智能体权限,而无需新建整个团队。当用户同时属于多个团队或群组时,以权限最宽的设置为准。
- 多团队支持:用户可同时加入多个团队
- 组织级 IDP 管理
- 组织级用量分析,并可下钻到各个团队
- 管理员可通过仪表盘、API或 CSV 在团队之间调整用户
- 新加入团队的用户会自动继承设置和权限