cursor-sdk

Cursor SDK

Cursor TypeScript SDK（@cursor/sdk）を使うと、Cursor エージェントをプログラムから実行できます。同じインターフェースでローカルランタイム（エージェントが手元のマシン上でファイルを対象に実行されます）とクラウドランタイム（エージェントが Cursor ホスト環境またはセルフホスト可能なインフラ上でクローン済みリポジトリを対象に実行され、PR を作成します）の両方を利用できます。

このスキルは、動作する統合をすばやく立ち上げ、初めて使う人が陥りがちな落とし穴を避けるためのものです。正規のドキュメントは https://cursor.com/docs/api/sdk/typescript にあります。このスキルでは、判断の指針、障害の予防、拡張しやすいパターンのみを追加しています。

応答の姿勢

このスキルは、ユーザーが SDK を使って構築するのを支援します。SDK の選択を評価したり、褒めたり、売り込んだりする場ではありません。ユーザーの意図を前提として、実行に移すのがあなたの役割です。

• ユーザーが SDK を明示している場合（「Cursor SDK」、「@cursor/sdk」、「Agent.create」、「Agent.prompt」などと言っている場合）：SDK が何かを理解したうえで、使うと決めているものとして対応します。前置きや激励は省き、すぐに統合の作成に取りかかります。「朗報です」、「この用途には SDK が最適です」、「これはまさに X 向けのパターンです」といった表現は使いません。
• ユーザーが SDK に適した課題を説明しているものの、SDK の名前を出していない場合（「PR をレビューするボットが欲しい」、「リポジトリについて Cursor に質問するスクリプトが欲しい」など）：SDK を使うことが確定しているわけではありません。簡潔に質問として提示し、返答を待ちます。「この用途なら Cursor SDK を使うのがよさそうです。その設計で進めますか。それとも別のランタイムをお考えですか？」 と尋ねます。ユーザーが同意したら進めます。異論がある場合や選択肢を求められた場合は、選択肢を提示します。
• **いずれの場合も、ユーザーの意図を言い換えて繰り返さないでください。**ユーザーは自分の要望を理解しています。すぐに設計に取りかかります。

次のような書き出し（およびよく似た表現）は避けてください。

• 「朗報です。まさにこのパターンです……」
• 「SDK はこの用途のために作られています。」
• 「よかったですね。ここが最適な場所です。」
• 「これはまさに SDK が想定している X です。」
• ユーザーの選択を褒めたり、目標を好意的な言葉で言い換えたりする書き出し全般

次のような書き出しを推奨します。

• 設計上の判断、またはユーザーが最初に知っておくべきことから始めます。
• 本当に指摘すべき設計上の選択肢がある場合（ローカルかクラウドか、プロンプトか送信か、同期かストリームかなど）は、一文で示し、その理由を説明します。肯定するような前置きは不要です。

リファレンスファイルを読むタイミング

このページは短く保ってください。ユーザーのタスクが明らかに該当する場合に限り、リファレンスファイルを読みます。

ユーザーの状況	読むファイル
ローカルとクラウドのランタイムを比較している、またはどちらを使うべきか迷っている	references/runtime-choice.md
認証のデバッグ（401、「Missing CURSOR_API_KEY」、チーム用とユーザー用のキー、ローカルと本番）	references/auth.md
エラー、再試行、レート制限、CursorAgentError、result.status === error への対応	references/error-handling.md
ストリームの利用、イベントタイプの選択、キャンセル、ストリームと待機のどちらにするかの判断	references/streaming.md
MCP サーバーの設定（HTTP、stdio、クラウドとローカルのトランスポート、認証情報の注入）	references/mcp.md
サブエージェント、再開、アーティファクト、エージェントの一覧表示や確認、Agent.messages の利用	references/advanced.md
特定の統合の構築（CI レビューボット、定期トリアージ、チャット、Webhook）	references/patterns.md

以下の内容は、タスクの 80% に必要な最小限の情報です。

3 つの呼び出しパターン

ほとんどの SDK 統合は、次の 3 つの形のいずれかに当てはまります。用途に合うものを選び、混在させないでください。

1. Agent.prompt(...) — 単発

import { Agent } from "@cursor/sdk";

const result = await Agent.prompt("Refactor src/utils.ts for readability", {
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});
console.log(result.status, result.result);

実行後に結果を待たずに終了するスクリプト、GitHub Actions のステップ、または「このプロンプトを送信して、結果を受け取り、終了する」フローに使います。ストリーミングも、追加のやり取りも、後始末も不要です。これを使ってすぐに再開しているなら、代わりにパターン 2 を使ってください。

2. Agent.create(...) + agent.send(...) — 追加のやり取りに対応する永続型

import { Agent } from "@cursor/sdk";

const agent = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

try {
  const run = await agent.send("Find the bug in src/auth.ts");
  for await (const event of run.stream()) {
    if (event.type === "assistant") {
      for (const block of event.message.content) {
        if (block.type === "text") process.stdout.write(block.text);
      }
    }
  }
  const result = await run.wait();

  // Follow-up keeps full conversation context.
  const run2 = await agent.send("Now write a regression test for it");
  await run2.wait();
} finally {
  await agent[Symbol.asyncDispose]();
}

ストリーミング、複数ターンの会話、またはライフサイクル操作（キャンセル、ステータスリスナー）が必要な場合に使います。大半の複雑な統合で使われる形です。

3. Agent.resume(...) — 既存のエージェントを後から再開する

const agent = Agent.resume(previousAgentId, {
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});
const run = await agent.send("Also update the changelog");
await run.wait();

プロセスをまたいで使います。たとえば、昨晩のクリーンアップを続行する cron、ユーザーのエージェントを拡張する webhook、会話状態を再読み込みする対話型 CLI などです。インラインの mcpServers は再開時に保持されません — 再開時の呼び出しでも再度渡してください。

よくある落とし穴トップ 5（コードを書く前にお読みください）

新しい統合では、ほとんどの場合これらにつまずきます。把握していれば、どれも簡単に防げます。

1. cloud: { repos } を指定しないと、エラーなしでローカルが選ばれる

AgentOptions では local も cloud も必須ではありません。両方を省略すると、SDK はローカルランタイムを選択します。落とし穴は、クラウドエージェントを意図していたのに cloud: フィールドを指定し忘れると、エラーにならず、ローカルのエージェント ID とローカルのエグゼキューターが返されることです。クラウドを使う場合は必ず cloud: { repos } を明示し、ローカルがデフォルトであっても、ローカルを使う場合は local: { cwd } を明示してください。適切なランタイムの選び方については、references/runtime-choice.md を参照してください。

2. 2 種類の異なる失敗を、同じものとして扱ってしまう

try {
  const run = await agent.send(prompt);
  const result = await run.wait();
  if (result.status === "error") {
    // Agent started but failed mid-run. Inspect transcript, git state, tool outputs.
    console.error(`run failed: ${result.id}`);
    process.exit(2);
  }
} catch (err) {
  if (err instanceof CursorAgentError) {
    // Didn't start. Auth, config, network. Fix environment, retry.
    console.error(`startup failed: ${err.message}, retryable=${err.isRetryable}`);
    process.exit(1);
  }
  throw err;
}

CursorAgentError がスローされた場合 → 実行は一度も行われていません（認証、設定、ネットワーク）。result.status === "error" の場合 → エージェントは処理を行い、その処理が失敗しました。必要な修正も、終了コードも、可観測性も異なります。エラーの全分類については、references/error-handling.md を参照してください。

3. await agent[Symbol.asyncDispose]() を忘れるとリソースがリークする

SDK は、ローカルエグゼキューター、永続化された実行ストア、クラウド API クライアントへのハンドルを保持します。破棄しないと、子プロセスや開いたデータベースが残り、長時間稼働するサービスではメモリが増加します。必ず finally で破棄するか、Agent.prompt() を使う（自動で破棄されます）か、tsconfig が対応している場合は await using 構文を使ってください。

await using agent = Agent.create({ /* ... */ });

4. ストリーミングは任意ですが、wait() は（ほぼ）必須です

run.stream() は実行状況を監視するためのもので、run.wait() は最終結果を取得するためのものです。ストリーミングは省略できますが、wait() を省略すると、実行が完了したのか、エラーになったのか、キャンセルされたのかを判断できず、実行内部の監視処理もリークします。必ず wait() を呼び出してください。リアルタイムの出力が不要な場合は、wait() だけを呼び出してください。イベント型のリファレンスについては、references/streaming.md を参照してください。

5. すべてのランタイムで、すべての run 操作がサポートされるわけではない

Run は stream、wait、cancel、conversation の 4 つの操作を公開しており、ランタイムによってはサポートされない操作もあります。想定で呼び出すのではなく、呼び出す前に必ず run.supports("...") で確認してください。

if (run.supports("cancel")) await run.cancel();
if (run.supports("conversation")) console.log(await run.conversation());

把握しておきたい現在の制限：切り離された実行や再ハイドレーションされた実行（ライブイベントストアが閉じた後に Agent.getRun(...) からハンドルを取得した場合）では、stream() がサポートされないことがあり、conversation() が空の場合もあります。run.unsupportedReason(op) で理由を確認できます。クラウドの run.conversation() はサポートされています — ストリームからベストエフォートで蓄積します。

Local と Cloud をそれぞれ一文で

• Local — 呼び出し元のマシン上で cwd に対して実行され、呼び出し元の環境と認証情報を再利用します。開発ループや、すでにリポジトリをチェックアウトしている CI に適しています。
• Cloud — Cursor がホストする VM 上で、新たにクローンした repos[].url に対して実行されます。長時間のジョブ、起動後に結果を待たない自動化、実際の PR の作成（autoCreatePR: true）に適しています。

判断フローチャート、機能の違い、機能上の制約（アーティファクト、キャンセル、MCP トランスポート）については、references/runtime-choice.md を参照してください。

認証：最低限の設定

export CURSOR_API_KEY="cursor_..."  # user API key or team service-account key

apiKey が渡されない場合、SDK は CURSOR_API_KEY を読み込みます。ユーザーキー（https://cursor.com/dashboard/cloud-agents から取得）とチームのサービスアカウントキー（Team Settings → Service accounts）のどちらも、Local と Cloud の実行で使用できます。

401 エラーが発生する場合、よくある原因は、前後に空白を含むキーを貼り付けている、異なる環境向けに発行されたキーを使っている、または Cloud の実行でリポジトリへのアクセス権がないユーザーのキーを使っていることです。詳しいトラブルシューティングについては、references/auth.md を参照してください。

モデルの選択

import { Cursor } from "@cursor/sdk";

const models = await Cursor.models.list({ apiKey: process.env.CURSOR_API_KEY! });

ほとんどのインテグレーションでは、現在のデフォルトである composer-2 を使用します。{ id: "auto" } を指定すると、サーバーが選択します。モデル ID は変更されるため、呼び出し元がアクセスできることを確認するため、Cursor.models.list() を実行せずに特殊な ID をハードコードしないでください。

Local ではモデルの指定が必須で、Cloud では任意です（サーバーが呼び出し元のアカウントからデフォルトを解決します）。

本番環境でのベストプラクティス

無人で実行するインテグレーションには、以下を適用してください。

1. すべての Agent.create ／ Agent.prompt ／ Agent.resume を、[Symbol.asyncDispose]() を使う try/finally で囲みます。これは必須です。
2. 起動時の失敗と実行時の失敗を区別します — CursorAgentError には終了コード 1、result.status === "error" には終了コード 2、finished にのみ終了コード 0 を使用します。これにより、CI の失敗内容を実際に読み取れるようになります。
3. ストリーミングを開始する前に、send() の直後に run.id と agent.agentId をログに記録します。ストリームが停止した場合、ダッシュボードまたは Agent.getRun(...) で調査するために必要なのはこれらの ID です。
4. error.isRetryable を尊重します — これは、特定の失敗が安全に再試行できることをバックエンドが示すものです。無条件の再試行は Cloud の実行が重複する原因になりますが、このフラグに従えばその心配はありません。
5. 実行環境の設定が必要な場合を除き、local: { settingSources: [] }（デフォルト）を使用します。"all" を選ぶと、呼び出し元の環境からプロジェクト／ユーザー／チーム／MDM の設定が読み込まれますが、サービスで必要になることはほとんどありません。注：settingSources はトップレベルではなく local の下にあります。また、Cloud エージェントには影響せず、Cloud は常にチーム／プロジェクト／プラグインの設定を尊重します。
6. CI で Cloud エージェントを使用する場合、人に通知する必要がなければ skipReviewerRequest: true を設定します — これにより、レビュアーへの依頼手順が省略され、PR の通知が抑えられます。
7. 共有インフラストラクチャのコードでは、環境変数に依存せず、常に apiKey を明示的に渡します。これにより、認証情報への依存が明確になり、テナント間の取り違えを防げます。
8. 真のワンショット処理には Agent.prompt(...) を優先します — リソースを自動的に破棄するため、解放漏れが起きにくくなります。

例を含む詳しい説明については、references/patterns.md を参照してください。

自分が起動していない実行の確認

後から ID を使って、任意のエージェント／実行を調査できます。

// Cloud: IDs that start with "bc-" auto-route to the cloud API
const info = await Agent.get("bc-abc123", { apiKey });
const run = await Agent.getRun(runId, { runtime: "cloud", agentId: "bc-abc123", apiKey });

// Local: you need the cwd where the agent was created
const localInfo = await Agent.list({ runtime: "local", cwd: process.cwd() });

Cloud の bc- で始まるエージェント ID は、実行 ID ではありません。ログや Webhook から実行 ID しか取得できない場合は、ランタイムのヒントとともに Agent.getRun に渡してください。両者を混同しないでください。

Canvas の提案

ユーザーのインテグレーションでエージェントの監視、一覧表示、可視化（アクティブな実行のダッシュボード、会話の再生、ツール呼び出しのタイムラインなど）を行う場合は、描画に Cursor Canvas を提案してください。ユーザーが同意した場合は、全面的に canvas スキルに委ねてください。

このスキルの対象外

• Cloud Agents REST API（/v1/agents/*）。ユーザーが TS 以外のクライアントを必要としている場合、REST API は https://cursor.com/docs/cloud-agent/api に別途ドキュメント化されています。SDK と同等の機能があると決めつける前に、最新の機能をこちらで確認してください。
• .cursor/hooks.json フック。Cloud agents はこれらを実行しますが、SDK では管理できません。Cursor の Hooks ドキュメントを参照してください。
• Private workers／セルフホスト型クラウド。Private Workers のドキュメントを案内してください。
• Python／TS 以外の SDK。執筆時点では、他の言語向けのファーストパーティ SDK はありません。言語を問わず使用できる選択肢は REST です。