# Cursorの機能と実践的な使い方
🧩 CursorのAIエージェントを、自前のスクリプトやCIチェックの中から呼び出せたら——。`
@cursor/sdk` はその願いを叶える、TypeScript製のエージェント操作インターフェースです。
🏷️ タイトル:
@cursor/sdk(TypeScript)
🔗 URL:
📘 概要
`
@cursor/sdk` は、IDE・CLI・Webアプリと同じCursorエージェントを、スクリプト可能なTypeScriptインターフェースとして公開するパッケージです。CI自動化、製品への組み込み、独自ワークフローのオーケストレーションなどに使えます。Node前提で、ローカル実行用コードは遅延ロードされるためクラウド専用利用では起動コストがかかりません。
⚙️ 機能の説明
主要な概念はAgent(会話文脈とワークスペース設定を保持するステートフルな入れ物)、Run(1回のプロンプト送信と、その出力ストリーム・状態・結果)、SDKMessage(実行中に流れる正規化済みイベント)です。
・`Agent.create()`:オプションを検証してすぐにハンドルを返し、`agent.send()` でプロンプトを送れます。
・local / cloud キー:実行場所を切り替えます。`local` はあなたのNodeプロセス内でエージェントループを回し、`cloud` はCursorホストの隔離VMでリポジトリを取得して動かします(自前VMプールも可)。
・「local」はエージェントループの場所を指すだけで、モデル推論は両モードともCursorのバックエンド経由です。
・`local.customTools` で独自関数をツールとして渡せます(ローカル専用)。`Agent.prompt()` はワンショット用のショートカットです。
🛠️ 実践的な使い方
インストールはスコープ付きの正確な名前 `npm install
@cursor/sdk` が必要です。
ローカルの作業ツリーに対してCIチェックを走らせるには、`Agent.create()` に `apiKey`・` を渡し、`agent.send()` でプロンプトを送って `run.wait()` の `status` が `finished` かを判定します。終わったら `agent[Symbol.asyncDispose]()` で後始末します。
クラウド実行に切り替えるなら `cloud` キーを使い、`autoCreatePR: true` で完了時にPRを開けます。認証は `CURSOR_API_KEY` 環境変数か `apiKey` 指定で、ユーザーキーまたはサービスアカウントキーが使えます。
💡 ユースケース
プルリクのCIで `Agent.prompt()` を回してセキュリティ監査を自動化したり、`cloud` キーで多数のエージェントを並列起動して大規模リファクタを別ブランチへPRさせたり、`local.customTools` で社内のデプロイ確認APIをエージェントに与えて自前ワークフローへ組み込む、といった使い方ができます。
⚠️ 注意点
ローカルモードはサンドボックスやhookを設定しない限り、シェル実行やファイル編集を承認なしで行います。CIでは `local.sandboxOptions: { enabled: true }` を検討してください。Python SDKは存在せず、Node以外の言語からはSDK Bridgeを使うか、Cloud AgentsのREST APIを直接叩きます。`Agent.resume()` ではインラインの `mcpServers` が失われるため再指定が必要で、モデルIDは変わり得るので `Cursor.models.list()` で確認するのが安全です。
#
Cursor# #
SDK#