Cursor SDK 近期核心更新解析：从连接稳定性到子智能体管理

Cursor SDK 近期更新日志速览

最近，Cursor 团队密集发布了多个版本的 SDK 更新，主要覆盖 npm 包 @cursor/sdk 和 PyPI 包 cursor-sdk。这些迭代集中在提升本地智能体的稳定性、修复网络连接异常和优化依赖管理等方面。以下是各版本的核心变更内容。

自定义工具可获取会话 ID在 TypeScript 环境下，local.customTools 的 execute 回调函数现在能接收 context.sessionId。这意味着主机程序可以识别是哪个本地会话调用了该工具。对于通过 Task 启动的子智能体，每个子智能体会传入独立的 ID，让状态管理更加精准。若运行时未提供会话 ID，该值将保持为空。
修复 FIPS 兼容性与类型定义本地智能体现在支持在启用 FIPS 标准的主机上运行，原有的存储机制也会自动迁移至新位置。恢复进程或虚拟机快照时，智能体不再复用旧的请求 ID 和会话 ID，避免了并发运行时的冲突。LocalSubagentInherit 类型不再依赖未发布的内部包，转而使用新导出的 LocalSubagentResourceProviderFields 和 LocalToolExecutor 类型，确保了类型解析的正确性。

支持子智能体继承父级配置设置 local.subagentInherit 后，由 Task 工具启动的子智能体（包括嵌套启动的）将继承父级的自定义 read、write、shell 执行器及工作区路径，并沿用相同的工具允许/排除列表。此功能可通过 Agent.create() 全局设置，或在单次 send 调用中覆盖。目前仅限 TypeScript 本地智能体使用。
解决长连接断开导致的请求卡死当智能体在两次运行之间空闲时，SDK 会在 29 秒后主动关闭未使用的 HTTP/2 连接。对于静默约一分钟的连接，SDK 会在复用前做健康检查，防止请求写入已关闭的服务器连接，这样避免请求挂起直到超时。
引入重试机制与上限若连接停滞，运行将失败并返回带有 connection_stalled 错误代码的可重试 NetworkError。SDK 限制了连续重试时长，最多持续 3 分钟，防止无限重试消耗资源。
精简依赖体积安装 @cursor/sdk 时，不再引入 @connectrpc/connect-node 或 undici 5.x，减少了依赖树的大小，同时消除了因版本冲突导致的审计警告。

后台等待期间支持即时引导此前，当智能体结束当前轮次等待后台子智能体时，run.steer(text) 会被解析为 revert_to_followup，需等待后台任务完成。现在，引导消息会作为下一轮次立即执行，而后台结果稍后返回。该特性仅适用于 TypeScript 本地运行。
新增工具请求完成事件当模型列出步骤中的所有工具调用后，onDelta 回调会触发 tool-requests-listed 事件，并附带 callCount 信息。虽然工具可能仍在运行，但开发者可据此判断所有工具调用已开始，用于 UI 中的分组或批处理展示。
修复云端代理 ID 冲突在创建云端代理时，若首次 send() 调用因 SDK 生成的 ID 冲突而失败，系统会自动改用新 ID 重试。若之前的创建请求已成功，则直接复用该智能体。恢复进程时，SDK 生成的智能体 ID 和运行 ID 也不再生成重复值。用户自定义的 ID 冲突仍会正常报错。
增强 Bridge 安全性独立的 cursor-sdk-bridge 可执行文件不再从工作目录加载 .env 或 bunfig.toml 文件。这防止了项目文件篡改 bridge 的端点、token 或预加载代码，提升了安全性。

后台子智能体结果回传当智能体在后台运行子智能体时，其结果现在会作为同一 run 中的后续请求轮次返回给父智能体，不再被丢弃。run.stream() 会在这些轮次中持续产出事件，run.wait() 则会等待这些轮次结束后才解析。此功能支持 TypeScript 和 Python 的本地智能体。
自定义工具标注TypeScript 中，local.customTools 条目支持 annotations 字段，可传递 MCP 工具标注（如 title、readOnlyHint 等）给模型。这些标注仅作为描述性提示，SDK 不会强制执行。
凭据自动刷新TypeScript 和 Python 的本地运行会在短期访问 token 过期前自动刷新，确保长时间运行（超过一小时）的智能体不会因身份验证错误而中断。云端运行不受此影响。

输出 Schema 支持TypeScript 和 Python 的自定义工具支持声明输出 Schema（outputSchema / output_schema），将 JSON Schema 公开给模型。结果不会按此 Schema 做校验，仅限本地智能体使用。
单文件 Bundle 优化在 Bun 环境下，@cursor/sdk 解析为扁平的单文件 bundle，使 bun build –compile 无需修改导入即可直接使用，解决了之前的打包报错问题。