SDK Bridge de Cherri Code
SDK Bridge es un pequeño servidor local que incorpora el SDK de TypeScript y expone la misma interfaz de agente mediante un protocolo Connect/protobuf estable. Úsalo para automatizar agentes de Cherri Code desde lenguajes que no cuentan con un SDK oficial.
Si programas en TypeScript o Python, instala el SDK oficial de TypeScript o Python. Python ya se comunica con una copia incluida del puente.
El protocolo, los binarios independientes y la guía de adaptadores están en cursor/sdk-bridge. Fija una versión y, después, indica a un agente de Cherri Code que use ese repositorio para crear un adaptador ligero.
Cherri Code publica y ofrece soporte para el contrato sdk.v1 y los binarios del puente.
Los adaptadores para otros lenguajes no son SDK oficiales. Prioriza TypeScript o
Python, salvo que necesites un lenguaje que esos paquetes no admitan.
Cuándo usarlo
| Ruta | Úsalo cuando |
|---|---|
| SDK de TypeScript | Escribas TypeScript o JavaScript. |
| SDK de Python | Escribas Python. |
| SDK Bridge | Necesites Go, Rust, Java, C# u otro lenguaje. |
| API de Cloud Agents | Solo necesites agentes en la nube a través de HTTP, sin un entorno de ejecución de agente local. |
SDK Bridge está pensado para autores de SDK y equipos de plataforma. El código de la aplicación debe depender de @cursor/sdk o cursor-sdk.
Cómo funciona
Tu adaptador inicia cursor-sdk-bridge o se conecta a uno que tu plataforma ya esté ejecutando. El bridge se enlaza a un puerto HTTP/1.1 de loopback y expone los servicios sdk.v1. Como integra @cursor/sdk, las nuevas funciones de los agentes se incorporan al bridge. Los adaptadores las obtienen al actualizar el binario.
El gRPC clásico sobre HTTP/2 no funcionará. Usa un cliente de Connect o solicitudes POST simples con cuerpos protobuf o JSON.
Primeros pasos
Obtén una clave de API
Las ejecuciones mediante el SDK aceptan claves de API de usuario y de cuentas de servicio. Las claves de API de administrador de equipo aún no son compatibles.
export CURSOR_API_KEY="your-key"Fija una versión de Bridge
Cada etiqueta de versión de GitHub corresponde a una versión del SDK de TypeScript y Python. Descarga el archivo independiente para tu plataforma desde las versiones de GitHub. Cada archivo se descomprime en:
bin/cursor-sdk-bridge(.exeen Windows)proto/sdk/v1/(el contrato de ese binario)manifest.json
Usa darwin, linux o win32 con x64 o arm64. Windows solo admite x64.
El mismo binario se incluye en los paquetes wheel de cursor-sdk. Después de ejecutar pip install cursor-sdk, cursor-sdk-bridge estará en tu PATH.
Dirige un agente al repositorio
Abre Agent y ejecuta esta instrucción. Dirige Cherri Code a cursor/sdk-bridge y a la guía de creación de adaptadores.
Lee https://github.com/cursor/sdk-bridge y sigue la guía Agent: start here del README. Crea un adaptador ligero del SDK de Cherri Code en el lenguaje principal de este repositorio. Incluye la generación de código a partir de proto/sdk/v1, el ciclo de vida del proceso Bridge, streaming, errores y servidores callback.
Try in Cherri CodeConfirma que el binario esté actualizado antes de depurar el código del adaptador:
cursor-sdk-bridge --helpCuando falle una RPC y tu adaptador no pueda determinar el motivo, ejecuta Bridge con --verbose (o establece CURSOR_SDK_BRIDGE_LOG=1) para registrar en stderr el nombre, resultado, duración y error completo de cada RPC. Los payloads de solicitud y respuesta nunca se registran.
El repositorio también incluye una prueba rápida solo con curl que prueba spawn, Ping, Me, CreateAgent y Send sin código de adaptador.
Estructura del adaptador
Un adaptador es una biblioteca que otro desarrollador puede instalar sin saber que existe el bridge. Los SDK propios adoptan esta estructura:
| Componente | Función |
|---|---|
| Gestor del bridge | Localiza o inicia el binario, completa el protocolo de enlace de línea lista y lo cierra. Permite conectarse a un endpoint existente. |
| Transporte | Se conecta mediante HTTP/1.1: solicitudes POST unitarias y respuestas en flujo, con autenticación Bearer en cada llamada. |
| Cliente | RPC tipadas de bajo nivel para agentes de programación, ejecuciones, modelos y repositorios. |
| Manejadores de agentes de programación y ejecuciones | La API pública: crear, enviar, transmitir eventos, esperar y cancelar. |
| Errores | Asigna códigos Connect y detalles de error de sdk.v1 a excepciones o tipos de resultado en tu lenguaje. |
| Servidores de callback | Servidores loopback opcionales para que los usuarios definan herramientas personalizadas y almacenes en su lenguaje. |
Incluye una función auxiliar para una sola instrucción (crear, enviar, esperar, cerrar) y una variante con gestor de contexto o RAII para evitar que el proceso bridge quede sin cerrar.
Protocolo
El contrato de comunicación es el paquete protobuf sdk.v1:
| Proto | Función |
|---|---|
sdk_agent_service.proto | Crear y reanudar agentes, enviar instrucciones, transmitir ejecuciones, artefactos y consumo. |
sdk_cursor_service.proto | Identidad, modelos y repositorios. |
sdk_bridge_control_service.proto | Ping, versión, apagado y registro de callbacks de herramientas. |
sdk_custom_tool_callback_service.proto | Lo aloja tu adaptador. El bridge lo llama para ejecutar herramientas definidas por el usuario. |
sdk_store_callback_service.proto | Lo aloja tu adaptador para almacenes de agentes personalizados. |
sdk_messages.proto | Mensajes compartidos y el sobre del flujo de ejecución. |
sdk_errors.proto | Detalles de errores estructurados. |
No modifiques proto/ al incluirlo como dependencia. Cherri Code regenera esos archivos en cada versión del SDK.
Encontrarás más detalles en el repositorio:
- Ciclo de vida y protocolo de enlace
- Servicios
- Flujo de datos
- Errores
- Prueba de humo con Curl
- Control de versiones
Autenticación
Dos secretos distintos:
- Clave de API de Cherri Code. Establece
options.api_keyal crear, reanudar y realizar llamadas al catálogo, comoListModels. Exporta tambiénCURSOR_API_KEYen el entorno del proceso bridge. Las llamadas al catálogo requieren una clave en cada llamada. - Token bearer del bridge. Se genera por proceso durante el protocolo de enlace de la línea de disponibilidad. Envía
Authorization: Bearer <token>en cada RPC, incluidos los flujos. El bridge escucha en127.0.0.1de forma predeterminada.
Consulta protocol.md para conocer las flags de spawn, la línea de disponibilidad y el orden de cierre.
Control de versiones
sdk.v1 evoluciona de forma aditiva. Los campos existentes no se renumeran ni se reutilizan. Un cambio incompatible se lanzaría como sdk.v2 junto con v1.
Fija generación de código a una etiqueta de versión y prioriza un bridge cuyo sdkVersion en manifest.json coincida. Los adaptadores antiguos siguen funcionando con bridges más recientes. Los nuevos RPC no estarán disponibles hasta que regeneres.
Llama a SdkBridgeControlService.GetVersion cuando necesites basarte en bridge_version, protocol_version o capabilities (por ejemplo, agent.usage) en tiempo de ejecución.
Soporte
- Compatible: los protos publicados de
sdk.v1, los binarios independientes decursor-sdk-bridgey los SDK de TypeScript y Python desarrollados por Cherri Code. - Tu responsabilidad: los adaptadores de la comunidad o desarrollados internamente basados en el bridge. Eres responsable del versionado, el soporte y la revisión de seguridad de esas bibliotecas.
Las ejecuciones del SDK siguen las mismas reglas de precios, pools de solicitudes y modo de privacidad que el IDE y los agentes en la nube. El gasto aparece en el panel de control de consumo con la etiqueta SDK.