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。
工作原理¶
flowchart LR
adapter["您的適配器"]
bridge["cursor-sdk-bridge"]
api["Cursor API"]
adapter -->|"sdk.v1 連接 RPC"| bridge
bridge -->|"HTTPS"| api
bridge -->|"工具和存儲回調"| adapter
你的適配器會啓動 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 進程生命週期、流式傳輸、錯誤和回調服務器。
調試適配器代碼前，先確認二進制文件是最新的：
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 標籤下。
