Cursor 近期更新了 TypeScript 与 Python 两套 SDK，核心变化在于赋予了开发者更大的控制权。现在可以灵活选择智能体元数据的持久化方式，直接注入自定义函数作为工具，利用自动审查机制管理本地工具调用，甚至支持子智能体无限层级嵌套。这次迭代还修复了大量底层问题，让 SDK 在 CI 流水线、生产环境脚本等无头场景中更稳定可靠。
接入自定义函数工具
过去若想让智能体调用自定义代码，得额外搭建 stdio 或 HTTP 协议的 MCP 服务器，配置繁琐。新版 SDK 通过 local.customTools 简化了这一流程：直接传入函数定义即可。这些工具会经由名为 custom-user-tools 的内置 MCP 服务器暴露给智能体，调用权限与标准 MCP 工具一致。支持在 Agent.create() 阶段全局设置，或在每次 send() 时动态指定。由于定义一次即可被父智能体及所有子智能体访问，整个运行链路都能复用。
自动审查本地工具调用
在无头运行模式下，本地智能体默认直接执行工具调用，因为缺乏人工交互。若需介入，可启用 local.autoReview 机制。这并非完全放行，而是引入分类器判断哪些调用可自动执行、哪些需暂停等待审查。开发者可通过 permissions.json 中的自然语言指令调控分类器行为：在 autoRun.allow_instructions 中描述允许的场景（如对构建产物做只读检查），在 autoRun.block_instructions 中描述需拦截的场景（如删除操作必须暂停），实现精细化的权限控制。
数据存储方案升级
SDK 需持久化智能体状态与运行元数据以支持进程重启恢复。原本仅支持 SQLite，现新增 JSONL 存储选项。JSONL 以纯文本追加写模式记录数据，便于直接读取、做 diff 对比或纳入版本控制。SqliteLocalAgentStore 与 JsonlLocalAgentStore 均支持导出。若需完全定制，可实现公开的 LocalAgentStore 接口并通过 local.store 注入，比如说为临时 CI 任务使用内存存储，或对接 Postgres 实现长期持久化。Python SDK 额外提供 host、JSONL 及组合式 JSONL 存储选项。
子智能体支持无限嵌套
子智能体现在可递归创建下级子智能体，形成多层委托结构。比如说审查智能体委派给测试编写智能体，后者还可继续向下分配任务。每层子智能体保留独立的提示词与模型配置。该功能默认生效，无需额外开关：子智能体会话会自动注册其调用 Task 所需的执行者，只要定义中声明了子智能体，嵌套逻辑即刻生效。
稳定性与性能优化
- 运行关联标识每次 send() 请求携带平台生成的 requestId，并同步暴露于 Run、RunResult 及各类存储中。该 ID 可直接关联后端日志、分析数据与支持工单，无需再依赖 agentId 推测。
- wait() 可靠性增强本地运行不再因终端结果未写完而提前结束 wait()。Hydration 机制持续刷新直至运行进入终态，确保自动化流程获取完整结果。
- 检查点保护机制释放本地智能体时，若根引用丢失但检查点 blob 仍存在，系统不再误删数据。仅当确认无保留内容时才清空智能体目录。
- HTTP/1.1 流式传输兼容云端会话现可正确处理经由旧版 Node fetch、特定代理或 CI 镜像的 HTTP/1.1 传输流，HTTP/2 行为保持不变。
- 轻量化导入@cursor/sdk 不再急切加载完整本地智能体栈。仅使用云端功能或类型声明时，可跳过本地运行时初始化开销，首次本地调用时再加载并缓存。
- TypeScript 类型自包含发布的 .d.ts 文件移除未发布包引用，解决 skipLibCheck: false 下的 TS2305/TS2307 报错及流类型被识别为 any 的问题。
- 内置 ripgrep本地 shell 运行使用包内平台专用 rg 二进制文件，不修改全局 PATH；Windows 环境下预置 ripgrep 亦不再覆盖 Path 变量。
- 模型路由升级固定使用已退役 composer-2 slug 的 SDK 客户端自动路由至 Composer 2.5，保留快速变体以保障旧脚本兼容。
- 工作区作用域 list_runsClient、AsyncClient 及 Agent.list_runs 新增可选 cwd 参数，bridge 进程回退至启动工作区，修复子进程运行时的“agent not found”误报。
- 错误提示优化查询不在已解析工作区中的智能体时，返回明确的未找到错误而非模糊内部错误。
- 分析追踪完善cursor-sdk 0.1.6 记录 Buildkite 发布路径，并将 SDK 调用标记为 sdk-python- 前缀，提升分析数据清晰度。
升级可通过 npm install @cursor/sdk 或 pip install cursor-sdk 完成。使用 composer-2 的脚本将自动迁移，requestId 可安全纳入运行元数据 schema。详细文档参见 TypeScript 与 Python 官方指南。
