# 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#