· Changelog

Changelog

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-2 slug 的 SDK 客户端，现在会自动路由到 Composer 2.5，同时保留快速变体，因此旧脚本也能继续运行。

  • 工作区作用域的 list_runs：Client、AsyncClient 和 Agent.list_runs 现在支持可选的 cwd，bridge 会回退到其启动时的工作区。当 bridge 作为子进程运行时，这修复了误报“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 也可以安全地加入您的运行元数据 schema。完整详情请参阅 TypeScript 和 Python 文档。