Cherri Code SDK Bridge
SDK Bridge は、TypeScript SDK を組み込み、安定した Connect/protobuf プロトコルを介して同じエージェント機能を公開する軽量なローカルサーバーです。ファーストパーティ SDK がない言語から Cherri Code エージェントをスクリプトで操作する際に使用します。
TypeScript または Python を使用する場合は、代わりにファーストパーティの TypeScript または Python SDK をインストールしてください。Python はすでにバンドル版の Bridge と通信します。
プロトコル、スタンドアロンバイナリ、アダプターガイドは cursor/sdk-bridge にあります。リリースを固定し、そのリポジトリを Cherri Code エージェントに指定して薄いアダプターを作成します。
Cherri Code は sdk.v1 コントラクトと Bridge バイナリを提供・サポートしています。
他言語のアダプターはファーストパーティ SDK ではありません。これらのパッケージで対応していない言語が必要な場合を除き、
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 を起動するか、プラットフォーム上ですでに実行中のものに接続します。ブリッジはループバックの HTTP/1.1 ポートにバインドし、sdk.v1 サービスを提供します。@cursor/sdk を組み込んでいるため、新しいエージェント機能はブリッジに追加されれば利用可能になります。アダプターはバイナリを更新することでそれらを利用できます。
従来の HTTP/2 上の gRPC では接続できません。Connect クライアント、または protobuf か JSON をボディに含む通常の POST を使用してください。
はじめ方
API キーを取得する
SDK 実行では、ユーザー API キーとサービスアカウントの API キーを使用できます。Team Admin API キーにはまだ対応していません。
export CURSOR_API_KEY="your-key"Bridge のリリースを固定する
各 GitHub リリースタグは、TypeScript SDK と 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 を開き、次のプロンプトを実行します。Cherri Code に cursor/sdk-bridge とアダプターのビルドガイドを参照させます。
https://github.com/cursor/sdk-bridge を読み、README の「Agent: start here」ガイドに従ってください。このリポジトリの主要言語で、最小限の Cherri Code SDK アダプターを作成してください。proto/sdk/v1 からのコード生成、bridge process のライフサイクル、ストリーミング、エラー、callback servers をカバーしてください。
Try in Cherri Codeアダプターコードをデバッグする前に、新しいバイナリであることを確認してください。
cursor-sdk-bridge --helpRPC が失敗し、アダプターで原因を確認できない場合は、--verbose を指定して bridge を実行します (または CURSOR_SDK_BRIDGE_LOG=1 を設定します) 。各 RPC の名前、結果、所要時間、完全なエラーが stderr に記録されます。リクエストとレスポンスのペイロードは記録されません。
このリポジトリには、アダプターコードなしで spawn、Ping、Me、CreateAgent、Send を実行する curl のみの smoke test もあります。
アダプターの構成
アダプターは、ブリッジの存在を意識せずに他の開発者がインストールできるライブラリです。Cherri Code 提供の SDK はこの構成に準拠します。
| 要素 | 役割 |
|---|---|
| ブリッジマネージャー | バイナリを検出または起動し、ready-line ハンドシェイクを完了して終了します。既存のエンドポイントへの接続も可能にします。 |
| トランスポート | HTTP/1.1 経由で接続します。単発の POST とストリーミングレスポンスを使用し、すべての呼び出しで Bearer 認証を行います。 |
| クライアント | エージェント、実行、モデル、リポジトリ向けの低レベルな型付き RPC。 |
| エージェントと実行のハンドル | 公開 API: 作成、送信、ストリームイベントの取得、待機、キャンセル。 |
| エラー | Connect コードと sdk.v1 のエラー詳細を、使用する言語の例外または結果型にマッピングします。 |
| コールバックサーバー | ユーザーが使用する言語でカスタムツールとストアを定義できるようにする、任意のループバックサーバー。 |
ワンプロンプト用ヘルパー (作成、送信、待機、終了) と、コンテキストマネージャーまたは RAII 形式を提供し、ブリッジプロセスのリークを防ぎます。
プロトコル
ワイヤーコントラクトは protobuf パッケージ sdk.v1 です。
| Proto | 役割 |
|---|---|
sdk_agent_service.proto | エージェントの作成と再開、プロンプトの送信、実行・アーティファクト・利用状況のストリーミング。 |
sdk_cursor_service.proto | ID、モデル、リポジトリ。 |
sdk_bridge_control_service.proto | Ping、バージョン、シャットダウン、ツールコールバックの登録。 |
sdk_custom_tool_callback_service.proto | アダプターでホストします。ブリッジはこれを呼び出して、ユーザー定義ツールを実行します。 |
sdk_store_callback_service.proto | カスタムエージェントストア用にアダプターでホストします。 |
sdk_messages.proto | 共有メッセージと実行ストリームのエンベロープ。 |
sdk_errors.proto | 構造化されたエラー詳細。 |
ベンダリングする際は proto/ を変更しないでください。Cherri Code は SDK のリリースごとにこれらのファイルを再生成します。
詳細はリポジトリを参照してください。
認証
2 種類のシークレット:
- Cherri Code API キー。
ListModelsなどの create、resume、catalog 呼び出しでは、options.api_keyを設定します。bridge プロセスの環境でCURSOR_API_KEYも export してください。catalog 呼び出しには、呼び出しごとのキーが必要です。 - Bridge bearer token。 ready-line ハンドシェイク中にプロセスごとに生成されます。streams を含むすべての RPC で、
Authorization: Bearer <token>を送信します。bridge はデフォルトで127.0.0.1でリッスンします。
spawn flags、ready line、シャットダウン順序については、protocol.mdを参照してください。
バージョニング
sdk.v1 では追加のみの変更が行われます。既存のフィールドの番号を変更したり、再利用したりすることはありません。破壊的変更は、v1 と並行して sdk.v2 として提供されます。
コード生成 はリリースタグに固定し、manifest.json の sdkVersion が一致する bridge を優先してください。古い アダプター も新しい bridge で引き続き動作します。新しい RPC は、再生成するまで利用できません。
実行時に bridge_version、protocol_version、または capabilities (例: agent.usage) に基づいて制御する必要がある場合は、SdkBridgeControlService.GetVersion を呼び出してください。
サポート
- サポート対象: 公開されている
sdk.v1プロト、スタンドアロンのcursor-sdk-bridgeバイナリ、ならびにファーストパーティの TypeScript および Python SDK。 - お客様の責任: bridge 上に構築されたコミュニティ製または社内製のアダプター。これらのライブラリのバージョニング、サポート、セキュリティレビューはお客様の責任となります。
SDK の実行には、IDE および Cloud Agents と同じ料金、リクエストプール、プライバシーモードのルールが適用されます。利用額は、利用ダッシュボードの SDK タグの下に表示されます。