Agent SDK
通过 TypeScript、Python 或 Bridge 在应用中创建、接续和管理 Cursor Agent。
This page has not been translated into English yet. The original Chinese version is shown below.
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 计入用户套餐。
In this section
- TypeScript SDK 入门安装 @cursor/sdk，配置用户认证，创建本地或云端 Agent 并释放资源。
- Python SDK 与异步客户端使用 Python dataclass 和显式 client 管理 Bridge、Agent 和一次性流。
- SDK 运行、事件与用量处理 Run 的最终结果和事件，区分语言差异、每轮统计与账单记录。
- SDK 模型与运行选项发现可用模型和 Router 模式，管理每轮覆盖、云端变量与自定义 metadata。
- SDK 配置与扩展加载 MCP、项目配置和 subagents，并在本地暴露自定义工具。
- SDK 工具权限与沙箱理解 headless 默认行为，组合工具限制、Hooks、沙箱和 Auto-review。
- SDK 持久化与恢复保存 Agent 标识和本地 checkpoint，恢复运行并管理资源生命周期。
- SDK Bridge 接入为其他语言构建 Connect/protobuf 适配层，管理本地服务的双重认证与版本。
- SDK 排障与错误处理定位认证、模型、集成、并发和运行时问题，保留可追踪的错误信息。