Cursor SDK升级：自定义工具、自动审查与嵌套Agent

2026 年 6 月 4 日 · 更新日志

我们在 TypeScript 和 Python SDK 中发布了一批新功能。现在你可以选择如何持久化 agent 和 run 元数据，将自己的函数作为工具暴露给 agent，通过自动审查路由本地工具调用，并将 subagent 嵌套到任意深度。此版本还带来了一系列可靠性、性能和平台修复，使本地和云 SDK agent 更容易在生产脚本、CI 和自定义集成中运行。

自定义工具

现在你可以通过 local.customTools 在 Agent.create() 或单个 send() 调用时向本地 agent 传递你自己的工具。SDK 通过一个名为 custom-user-tools 的内置 MCP 服务器将其暴露给 agent，因此模型通过与任何其他 MCP 工具相同的路径和相同的权限门槛调用你的代码。

之前，暴露自定义能力意味着要搭建自己的 stdio 或远程 HTTP MCP 服务器并将其接入 agent。现在只需要一个函数定义就够了。自定义工具对 parent agent 的每个 subagent 都是可见的，所以一个你定义的工具在整个 run 过程中都是可用的。

自动审查

默认情况下，本地 SDK agent 在运行工具调用时不需要征求批准，因为在无人值守的运行中没有人类在循环中。设置 local.autoReview 将这些调用通过自动审查来路由。一个分类器决定哪些调用自动运行，哪些暂停以待审查，而不是完全绕过审查。

你可以在 permissions.json 中使用自然语言指令来引导这个分类器。autoRun.allow_instructions 字段描述倾向于允许的调用形状，autoRun.block_instructions 描述要暂停以待审查的调用。例如，你可以允许对 ./dist 下的构建工件进行只读检查，同时总是在删除等破坏性操作上暂停。

{
  "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 都持久化 agent 和 run 元数据，以便你可以在进程重启后恢复 agent。到目前为止，该存储是 SQLite。现在你可以选择使用 JSONL 存储，它写入一个纯粹的、仅追加的文件，你可以读取、diff 和检入版本控制。SqliteLocalAgentStore 和 JsonlLocalAgentStore 都直接导出。

如果两个默认都不适合你的设置，实现公共的 LocalAgentStore 接口并通过 local.store 传递它。为短暂的 CI 运行构建内存存储，或者当你希望 agent 状态与应用程序的其余数据一起存储时，用 Postgres 支持持久化。Python SDK 通过桥接暴露主机、JSONL 和组合 JSONL 存储。

嵌套 subagent

Subagent 现在可以生成自己的 subagent，以此类推。一个审查者 subagent 可以委托给测试编写器，它可以进一步委托，每个级别都保持自己的 prompt 和模型。没有什么需要打开；一个 subagent 会话注册它需要调用 Task 的执行器，所以嵌套对任何定义 subagent 的 agent 都能自动工作。

可靠性、性能和平台改进

此版本还包括跨两个 SDK 的一批生活质量修复。

Run 关联

每个 send() 现在都携带一个平台生成的 requestId，暴露在 Run 和 RunResult 上，并在内存、SQLite 和 JSONL 存储中持久化。将脚本或 CI 运行与后端日志、分析和支持线程相关联，无需从 agentId 推断。

本地运行上的可靠 wait()

本地运行不再在终端结果写入前解析 wait()。Hydration 会继续刷新，直到 run 达到最终状态，所以自动化读取完整的结果。

处置时的安全检查点

处置本地 agent 不再在根引用缺失但检查点 blob 仍存在时删除检查点数据。只有当确实没有任何东西可保留时，agent 目录才会被清除。

HTTP/1.1 上的云流

云 agent 会话现在在某些代理、较旧的 Node fetch 栈和某些 CI 镜像使用的 HTTP/1.1 传输上正确流式传输。HTTP/2 行为不变。

更轻量的导入

导入 @cursor/sdk 不再急切加载完整的本地 agent 栈。仅云和仅类型的消费者在第一次本地调用前跳过本地运行时成本，没有 API 变化。第一次本地调用支付一次性导入，然后保持缓存。

自包含的 TypeScript 类型

发布的 .d.ts 文件不再引用未发布的工作空间包。这修复了在 skipLibCheck: false 和 stream 类型（如 TurnEndedUpdate）上的静默 any 时的 TS2305 和 TS2307 错误。

捆绑的 ripgrep

本地 shell 运行使用捆绑的平台 rg 二进制文件，不修改你的全局 PATH。在 Windows 上，预置 ripgrep 不再会覆盖 Path 变量。

Composer 2 路由到 Composer 2.5

仍然固定已废弃 composer-2 slugs 的 SDK 客户端会自动路由到 Composer 2.5，保持快速变体完整，所以较旧的脚本继续运行。

工作空间范围的 list_runs

Client、AsyncClient 和 Agent.list_runs 接受可选的 cwd，桥接器回退到其启动工作空间。这修复了当桥接器作为子进程运行时的虚假"agent not found"结果。

更清晰的 not-found 错误

查找不在解析工作空间中的 agent 现在返回清晰的 not-found 错误，而不是不透明的内部错误。

0.1.6 版本和分析

cursor-sdk 0.1.6 记录了 Buildkite 发布路径，并将 SDK 使用标记为 sdk-python- 以获得更清晰的分析。

运行 npm install @cursor/sdk 或 pip install cursor-sdk 来升级。固定 composer-2 的脚本会自动移动到 Composer 2.5，requestId 是对你的运行元数据模式的安全补充。有关完整详情，请参见 TypeScript 和 Python 文档。