Ponte do Cherri Code SDK
A Ponte do SDK é um pequeno servidor local que incorpora o SDK para TypeScript e expõe a mesma interface de agente por um protocolo Connect/protobuf estável. Use-a para criar scripts com agentes do Cherri Code em linguagens que não têm um SDK oficial.
Se você usa TypeScript ou Python, instale o SDK oficial de TypeScript ou Python. O Python já se comunica com uma cópia integrada da ponte.
O protocolo, os binários independentes e o guia de adaptadores estão em cursor/sdk-bridge. Fixe uma versão e aponte um agente do Cherri Code para esse repositório para criar um adaptador simples.
O Cherri Code publica e oferece suporte ao contrato sdk.v1 e aos binários da ponte.
Adaptadores em outras linguagens não são SDKs oficiais. Priorize TypeScript ou
Python, a menos que precise de uma linguagem não contemplada por esses pacotes.
Quando usar
| Caminho | Use quando |
|---|---|
| TypeScript SDK | Você estiver escrevendo em TypeScript ou JavaScript. |
| Python SDK | Você estiver escrevendo em Python. |
| Ponte do SDK | Precisar usar Go, Rust, Java, C# ou outra linguagem. |
| Cloud Agents API | Só precisar de agentes em nuvem via HTTP, sem um agente local em execução. |
A ponte é destinada a autores de SDKs e equipes de plataforma. O código da aplicação deve depender de @cursor/sdk ou cursor-sdk.
Como funciona
Seu adaptador cria cursor-sdk-bridge ou se conecta a uma instância já executada pela sua plataforma. A ponte abre uma porta HTTP/1.1 de loopback e expõe os serviços sdk.v1. Como incorpora @cursor/sdk, novas funcionalidades de agente são integradas à ponte. Os adaptadores passam a usá-las ao atualizar o binário.
O gRPC clássico sobre HTTP/2 não se conecta. Use um cliente Connect ou requisições POST simples com corpos protobuf ou JSON.
Introdução
Obtenha uma chave de API
As execuções do SDK aceitam chaves de API de usuário e de conta de serviço. As chaves de API de administração da equipe ainda não são compatíveis.
export CURSOR_API_KEY="your-key"Fixe uma versão da ponte
Cada tag de lançamento do GitHub corresponde à versão dos SDKs TypeScript e Python. Baixe o arquivo independente para sua plataforma nas versões do GitHub. Cada arquivo é descompactado em:
bin/cursor-sdk-bridge(.exeno Windows)proto/sdk/v1/(o contrato desse binário)manifest.json
Use darwin, linux ou win32 com x64 ou arm64. No Windows, apenas x64 é compatível.
O mesmo binário vem incluído nos pacotes wheel do cursor-sdk. Após executar pip install cursor-sdk, cursor-sdk-bridge estará no seu PATH.
Aponte um agente para o repositório
Abra o Agent e execute este prompt. Ele direciona o Cherri Code para cursor/sdk-bridge e para o guia de criação de adaptadores.
Leia https://github.com/cursor/sdk-bridge e siga o guia Agent: comece aqui no README. Crie um adaptador Cherri Code SDK simples na linguagem principal deste repositório. Inclua geração de código a partir de proto/sdk/v1, ciclo de vida do processo da ponte, streaming, erros e servidores de callback.
Try in Cherri CodeConfirme que o binário está atualizado antes de depurar o código do adaptador:
cursor-sdk-bridge --helpQuando uma RPC falhar e você não conseguir identificar o motivo no adaptador, execute a ponte com --verbose (ou defina CURSOR_SDK_BRIDGE_LOG=1) para registrar no stderr o nome, resultado, duração e erro completo de cada RPC. As cargas úteis de solicitação e resposta nunca são registradas.
O repositório também tem um teste rápido apenas com curl que testa spawn, Ping, Me, CreateAgent e Send sem código de adaptador.
Estrutura do adaptador
Um adaptador é uma biblioteca que outro desenvolvedor pode instalar sem saber que a ponte existe. Os SDKs oficiais seguem este padrão:
| Componente | Função |
|---|---|
| Gerenciador da ponte | Localizar ou criar o binário, concluir o handshake da ready-line e encerrá-lo. Permitir conexão a um endpoint existente. |
| Transporte | Conectar via HTTP/1.1: POSTs unários e respostas em stream, com autenticação bearer em todas as chamadas. |
| Cliente | RPCs tipadas de baixo nível para agentes, execuções, modelos e repositórios. |
| Handles de Agente e Execução | A API pública: criar, enviar, transmitir eventos, aguardar e cancelar. |
| Erros | Mapear códigos Connect e detalhes de erro sdk.v1 para exceções ou tipos de resultado na sua linguagem. |
| Servidores de callback | Servidores loopback opcionais para que os usuários possam definir ferramentas personalizadas e stores na sua linguagem. |
Forneça um auxiliar para um único prompt (criar, enviar, aguardar, fechar) e uma versão com gerenciador de contexto ou RAII para evitar vazamentos no processo da ponte.
Protocolo
O contrato de comunicação é o pacote protobuf sdk.v1:
| Proto | Função |
|---|---|
sdk_agent_service.proto | Cria e retoma agentes, envia prompts e transmite execuções, artefatos e dados de uso. |
sdk_cursor_service.proto | Identidade, modelos e repositórios. |
sdk_bridge_control_service.proto | Ping, versão, encerramento e registro de callbacks de ferramentas. |
sdk_custom_tool_callback_service.proto | Hospedado pelo seu adaptador. A ponte o chama para executar ferramentas definidas pelo usuário. |
sdk_store_callback_service.proto | Hospedado pelo seu adaptador para stores personalizados de agentes. |
sdk_messages.proto | Mensagens compartilhadas e o envelope do stream de execução. |
sdk_errors.proto | Detalhes estruturados de erros. |
Não altere proto/ ao incluí-lo como dependência. O Cherri Code regenera esses arquivos a cada lançamento do SDK.
Os detalhes estão no repositório:
Autenticação
Dois segredos distintos:
- Chave de API do Cherri Code. Defina
options.api_keyao criar, retomar e fazer chamadas ao catálogo, comoListModels. Exporte tambémCURSOR_API_KEYno ambiente do processo da ponte. As chamadas ao catálogo exigem uma chave em cada chamada. - Token bearer da ponte. Gerado para cada processo durante o handshake da ready-line. Envie
Authorization: Bearer <token>em todas as RPCs, incluindo streams. Por padrão, a ponte escuta em127.0.0.1.
Consulte protocol.md para ver as flags de criação, a ready line e a ordem de encerramento.
Versionamento
sdk.v1 evolui de forma aditiva. Os campos existentes não são renumerados nem reutilizados. Uma alteração incompatível seria lançada como sdk.v2, em paralelo ao v1.
Fixe o codegen em uma tag de lançamento e prefira uma ponte cujo sdkVersion em manifest.json corresponda. Adaptadores antigos continuam funcionando com pontes mais recentes. Novos RPCs permanecem indisponíveis até que você regenere.
Chame SdkBridgeControlService.GetVersion quando precisar condicionar o comportamento a bridge_version, protocol_version ou capabilities (por exemplo, agent.usage) em tempo de execução.
Suporte
- Com suporte: os protos
sdk.v1publicados, os binários independentes docursor-sdk-bridgee os SDKs oficiais para TypeScript e Python. - Sua responsabilidade: adaptadores da comunidade ou internos criados com base na ponte. Você é responsável pelo versionamento, suporte e revisão de segurança dessas bibliotecas.
As execuções do SDK seguem as mesmas regras de preço, pools de solicitações e Privacy Mode do IDE e dos agentes em nuvem. Os gastos aparecem no dashboard de uso com a tag SDK.