Agent SDK

SDK 将本地与云端 Agent 放到同一套编程接口中。本地指 Agent 循环和文件访问在本机，模型推理仍经过 Cursor 托管服务。只需要远程 HTTP 工作流时也可使用Cloud Agents API。

选择语言与运行时

入口	适用方式
@cursor/sdk	TypeScript/JavaScript，Node.js 22.13 或以上
cursor-sdk	Python 3.10 或以上，同步与异步接口，内置 Bridge
SDK Bridge	其他语言的 SDK 适配层，通过 Connect/protobuf 调用本地服务

本地适合已有 checkout 的脚本和 CI，云端适合远程仓库和调用方断开后继续执行的任务。SDK 不是通用 chat-completions API。

学习路径

• TypeScript 入门：安装、认证、首轮运行与打包。
• Python 入门：dataclass、同步及异步 client。
• 运行与事件：结果、取消、steering 和 token 用量。
• 模型与环境：Router、每轮选项与云端变量。
• 配置与扩展：MCP、subagents、Hooks 和 custom tools。
• 权限与沙箱：默认执行行为、工具限制与 Auto-review。
• 持久化与恢复：本地 store、恢复句柄和归档。
• Bridge：其他语言接入的协议、凭据和版本。
• SDK 排障：错误类型、运行状态和诊断。

SDK 使用与 IDE/Cloud Agents 相同的计价、请求池和 Privacy Mode 规则，用量在 dashboard 标记为 SDK。服务账号 key 计入所属团队，用户 key 计入用户套餐。