Cursor SDK Bridge
SDK Bridge 是一个小型本地服务器，内嵌 TypeScript SDK，并通过稳定的 Connect/protobuf 协议提供相同的智能体功能。您可以使用它通过没有第一方 SDK 的语言编写脚本来调用 Cursor 智能体。
如果您使用 TypeScript 或 Python，请改为安装第一方 TypeScript 或 Python SDK。Python 可直接与随附的 bridge 副本通信。
协议、独立二进制文件和 adapter 指南位于 cursor/sdk-bridge。固定一个发布版本，然后让 Cursor 智能体基于该仓库构建一个轻量级 adapter。
Cursor 发布并支持 sdk.v1 合约和 bridge 二进制文件。
其他语言的 adapter 并非第一方 SDK。除非需要这些 package 未覆盖的语言，
否则请优先使用 TypeScript 或 Python。
适用场景
| 路径 | 适用场景 |
|---|---|
| TypeScript SDK | 使用 TypeScript 或 JavaScript 开发。 |
| Python SDK | 使用 Python 开发。 |
| SDK Bridge | 需要使用 Go、Rust、Java、C# 或其他语言。 |
| Cloud Agents API | 只需通过 HTTP 使用云端代理，无需本地代理运行时。 |
Bridge 面向 SDK 作者和平台团队。应用代码应依赖 @cursor/sdk 或 cursor-sdk。
工作原理
你的适配器会启动 cursor-sdk-bridge，或连接到平台已运行的实例。Bridge 会绑定一个本地回环 HTTP/1.1 端口，并提供 sdk.v1 服务。由于 Bridge 内嵌 @cursor/sdk，新的智能体功能会先合入 Bridge。适配器只需升级二进制文件即可获得这些功能。
传统的基于 HTTP/2 的 gRPC 无法连接。请使用 Connect 客户端，或发送包含 protobuf 或 JSON 请求体的普通 POST 请求。
快速入门
获取 API 密钥
SDK 运行支持用户 API 密钥和服务账户 API 密钥，暂不支持团队管理员 API 密钥。
export CURSOR_API_KEY="your-key"固定 Bridge 版本
每个 GitHub 发布标签都对应 TypeScript 和 Python SDK 的版本。从 GitHub releases 下载适用于你平台的独立归档文件。每个归档文件解压后包含：
bin/cursor-sdk-bridge(Windows 上为.exe)proto/sdk/v1/(该二进制文件的合约)manifest.json
使用 darwin、linux 或 win32，并搭配 x64 或 arm64。Windows 仅支持 x64。
同一二进制文件也包含在 cursor-sdk wheel 包中。执行 pip install cursor-sdk 后，cursor-sdk-bridge 会添加到你的 PATH 中。
让智能体使用代码仓库
打开 Agent 并运行以下提示词。它会让 Cursor 了解 cursor/sdk-bridge 和适配器构建指南。
阅读 https://github.com/cursor/sdk-bridge，并遵循 README 中的“Agent: start here”指南。使用此代码仓库的主要语言构建一个精简的 Cursor SDK 适配器。涵盖从 proto/sdk/v1 进行代码生成、Bridge 进程生命周期、流式传输、错误和回调服务器。
Try in Cursor调试适配器代码前，先确认二进制文件是最新的：
cursor-sdk-bridge --help如果 RPC 失败且你的适配器无法确定原因，请使用 --verbose 运行 Bridge (或设置 CURSOR_SDK_BRIDGE_LOG=1) ，以将每个 RPC 的名称、结果、耗时和完整错误记录到 stderr。请求和响应负载绝不会被记录。
该代码仓库还提供了一个仅用 curl 的冒烟测试，无需编写适配器代码即可测试 spawn、Ping、Me、CreateAgent 和 Send。
适配器结构
适配器是一个库，其他开发者无需了解 Bridge 的存在即可安装。第一方 SDK 均采用以下结构：
| 组成 | 职责 |
|---|---|
| Bridge 管理器 | 查找或启动二进制文件，完成 ready-line 握手，并在结束时关闭它。支持连接到现有端点。 |
| 传输层 | 通过 HTTP/1.1 连接：使用一元 POST 和流式响应，并为每次调用添加 Bearer 认证。 |
| 客户端 | 提供面向智能体、运行、模型和仓库的底层强类型 RPC。 |
| 智能体和运行句柄 | 公共 API：创建、发送、流式接收事件、等待和取消。 |
| 错误 | 将 Connect 代码和 sdk.v1 错误详情映射为所用语言中的异常或结果类型。 |
| 回调服务器 | 可选的回环服务器，让用户能以所用语言定义自定义工具和存储。 |
提供单提示词助手 (创建、发送、等待、关闭) ，以及上下文管理器或 RAII 形式，避免 Bridge 进程泄漏。
协议
线缆协议合约为 protobuf 包 sdk.v1：
| Proto | 作用 |
|---|---|
sdk_agent_service.proto | 创建和恢复智能体、发送提示词，以及流式传输运行、产物和用量。 |
sdk_cursor_service.proto | 身份、模型和仓库。 |
sdk_bridge_control_service.proto | Ping、版本、关闭和工具回调注册。 |
sdk_custom_tool_callback_service.proto | 由您的适配器托管。bridge 会调用它来运行用户定义的工具。 |
sdk_store_callback_service.proto | 由您的适配器托管，用于自定义智能体存储。 |
sdk_messages.proto | 共享消息和运行流封装。 |
sdk_errors.proto | 结构化错误详情。 |
通过 vendor 引入时，请勿修改 proto/。Cursor 会在每次 SDK 发布时重新生成这些文件。
详细说明请参阅仓库：
身份验证
两种独立的机密信息：
- Cursor API 密钥。 在 create、resume 和
ListModels等 catalog 调用中设置options.api_key。还需在桥接进程的环境中导出CURSOR_API_KEY。Catalog 调用需要为每次调用提供密钥。 - Bridge Bearer 令牌。 在 ready-line 握手期间为每个进程生成。每次 RPC (包括流式传输) 都应发送
Authorization: Bearer <token>。默认情况下，桥接服务监听127.0.0.1。
有关 spawn 标志、ready line 和关闭顺序，请参阅 protocol.md。
版本管理
sdk.v1 仅以增量方式演进。现有字段不会重新编号或复用。破坏性更改将以 sdk.v2 的形式与 v1 并行上线。
将 codegen 固定到发布标签，并优先选择 manifest.json 中 sdkVersion 相匹配的 bridge。较早的适配器仍可与较新的 bridge 配合使用。新的 RPC 在重新生成前不会生效。
需要在运行时根据 protocol_version 或 capabilities 进行条件控制时，请调用 SdkBridgeControlService.GetVersion。
支持
- **支持范围：**已发布的
sdk.v1proto、独立的cursor-sdk-bridge二进制文件，以及第一方 TypeScript 和 Python SDK。 - **您的责任：**基于桥接器构建的社区或内部适配器。您负责这些库的版本管理、支持和安全评审。
SDK 运行与 IDE 和云端代理适用相同的定价、请求用量池和隐私模式规则。费用会显示在用量仪表盘的 SDK 标签下。