Cursor SDK Bridge
SDK Bridge — это небольшой локальный сервер, который встраивает TypeScript SDK и предоставляет те же возможности агента через стабильный протокол Connect/protobuf. Используйте его для написания скриптов для агентов Cursor на языках, для которых нет собственного SDK.
Если вы пишете на TypeScript или Python, установите собственный TypeScript или Python SDK. Python уже взаимодействует со встроенной копией bridge.
Протокол, автономные бинарные файлы и руководство по созданию адаптера доступны в cursor/sdk-bridge. Зафиксируйте релиз, затем укажите агенту Cursor этот репозиторий, чтобы создать небольшой адаптер.
Cursor публикует и поддерживает контракт sdk.v1 и бинарные файлы bridge.
��даптеры для других языков не являются собственными SDK. Используйте TypeScript или
Python, если только вам не нужен язык, который эти пакеты не поддерживают.
Когда использовать
| Путь | Используйте, если |
|---|---|
| TypeScript SDK | Вы пишете на TypeScript или JavaScript. |
| Python SDK | Вы пишете на Python. |
| SDK Bridge | Вам нужен Go, Rust, Java, C# или другой язык. |
| API облачных агентов | Вам нужны только облачные агенты по HTTP, без локальной среды выполнения агента. |
Bridge предназначен для авторов SDK и команд, разрабатывающих платформы. Код приложений должен зависеть от @cursor/sdk или cursor-sdk.
Как это работает
Ваш адаптер запускает cursor-sdk-bridge или подключается к экземпляру, уже запущенному на вашей платформе. Bridge привязывается к локальному порту HTTP/1.1 и предоставляет сервисы sdk.v1. Поскольку Bridge содержит @cursor/sdk, новые функции Agent появляются в нём сразу. Адаптеры получают их после обновления бинарного файла.
Классический gRPC поверх HTTP/2 не поддерживается. Используйте клиент Connect или обычные запросы POST с телом в формате protobuf или JSON.
Быстрый старт
Получите API-ключ
SDK-запуски принимают пользовательские API-ключи и API-ключи сервисных аккаунтов. API-ключи Team Admin пока не поддерживаются.
export CURSOR_API_KEY="your-key"Закрепите релиз bridge
Каждый тег релиза GitHub соответствует версии SDK для TypeScript и Python. Скачайте автономный архив для своей платформы из релизов GitHub. Каждый архив содержит:
bin/cursor-sdk-bridge(.exeв Windows)proto/sdk/v1/(контракт для этого бинарного файла)manifest.json
Используйте darwin, linux или win32 с x64 или arm64. Для Windows доступен только x64.
Этот же бинарный файл входит в wheel-пакеты cursor-sdk. После pip install cursor-sdk cursor-sdk-bridge будет доступен в вашем PATH.
Направьте Agent на репозиторий
Откройте Agent и запустите этот промпт. Он направит Cursor к cursor/sdk-bridge и руководству по созданию адаптера.
Прочитайте https://github.com/cursor/sdk-bridge и следуйте руководству Agent: start here в README. Создайте тонкий адаптер Cursor SDK на основном языке этого репозитория. Охватите codegen из proto/sdk/v1, жизненный цикл процесса bridge, стриминг, ошибки и серверы обратного вызова.
Try in CursorПеред отладкой кода адаптера убедитесь, что используется свежий бинарный файл:
cursor-sdk-bridge --helpЕсли RPC завершается ошибкой и ваш адаптер не позволяет понять причину, запустите bridge с --verbose (или установите CURSOR_SDK_BRIDGE_LOG=1), чтобы записывать в stderr имя, результат, длительность и полную ошибку каждого RPC. Payload запросов и ответов никогда не записываются в журнал.
В репозитории также есть smoke test только с curl, который проверяет spawn, Ping, Me, CreateAgent и Send без кода адаптера.
Структура адаптера
Адаптер — это библиотека, которую другой разработчик может установить, даже не зная о существовании Bridge. Собственные SDK имеют такую структуру:
| Компонент | Назначение |
|---|---|
| Менеджер Bridge | Находит или запускает бинарный файл, выполняет handshake по строке готовности и завершает работу процесса. Позволяет подключаться к существующему endpoint. |
| Транспорт | Подключается по HTTP/1.1: унарные POST-запросы и потоковые ответы, с bearer-аутентификацией для каждого вызова. |
| Клиент | Низкоуровневые типизированные RPC для агентов, запусков, моделей и репозиториев. |
| Дескрипторы Agent и Run | Публичный API: создать, отправить, получать события потока, ожидать и отменять. |
| Ошибки | Сопоставляют коды Connect и сведения об ошибках sdk.v1 с исключениями или типами результатов в вашем языке. |
| Серверы обратных вызовов | Необязательные loopback-серверы, позволяющие пользователям определять пользовательские инструменты и хранилища на вашем языке. |
Добавьте помощник для одного промпта (создать, отправить, ожидать, закрыть) и вариант с контекстным менеджером или RAII, чтобы процесс Bridge не оставался запущенным.
Протокол
Контракт wire-формата описан в protobuf-пакете sdk.v1:
| Proto | Назначение |
|---|---|
sdk_agent_service.proto | Создание и возобновление работ�� агентов, отправка промптов, стриминг запусков, артефактов и данных об использовании. |
sdk_cursor_service.proto | ��дентификация, модели и репозитории. |
sdk_bridge_control_service.proto | Ping, версия, завершение работы и регистрация callback-функций инструментов. |
sdk_custom_tool_callback_service.proto | Размещается в вашем адаптере. Bridge вызывает его для запуска пользовательских инструментов. |
sdk_store_callback_service.proto | Размещается в вашем адаптере для пользовательских хранилищ агентов. |
sdk_messages.proto | Общие сообщения и обёртка потока запусков. |
sdk_errors.proto | Структурированные сведения об ошибках. |
Не изменяйте proto/ при вендоринге. Cursor повторно генерирует эти файлы при каждом релизе SDK.
Подробности — в репозитории:
Аутентификация
Два отдельных секрета:
- API-ключ Cursor. Задайте
options.api_keyпри вызовах создания, возобновления и получения каталога, напримерListModels. Также экспортируйтеCURSOR_API_KEYв окружение процесса bridge. Для вызовов каталога требуется ключ в каждом вызове. - Bearer-токен bridge. Генерируется для каждого процесса во время handshake по строке готовности. Передавайте
Authorization: Bearer <token>в каждом RPC-вызове, включая потоки. По умолчанию bridge прослушивает127.0.0.1.
См. protocol.md с описанием флагов запуска, строки готовности и порядка завершения работы.
Управление версиями
sdk.v1 изменяется только с добавлением новых возможностей. Существующие поля не перенумеровываются и не используются повторно. Несовместимые изменения будут выпускаться как sdk.v2 наряду с v1.
Закрепляйте codegen за тегом релиза и выбирайте bridge, у которого значение sdkVersion в manifest.json совпадает. Прежние адаптеры продолжают работать с более новыми bridge. Новые RPC остаются недоступными, пока не будет выполнена повторная генерация.
Вызывайте SdkBridgeControlService.GetVersion, когда во время выполнения нужно проверять protocol_version или capabilities.
Поддержка
- Поддерживается: опубликованные протоколы
sdk.v1, автономные бинарные файлыcursor-sdk-bridge, а также собственные SDK для TypeScript и Python. - Ваша ответственность: адаптеры сообщества или внутренние адаптеры, созданные на основе bridge. Вы отвечаете за управление версиями, поддержку и проверку безопасности этих библиотек.
Для запусков SDK действуют те же правила ценообразования, пулов запросов и режима конфиденциальности, что и для IDE и Cloud Agents. Расходы отображаются на дашборде использования с тегом SDK.