Cursor SDK が発表されたので使ってみる

Cursor SDK が発表されたので使ってみる

Cursor SDK を使って、TypeScript から Cursor Agent を起動してみました。API キーの作成、料金の扱い、利用可能なモデル一覧、ローカルファイルを読ませる簡単なサンプルまで確認します。
2026.04.30

リテールアプリ共創部の末永です。

Cursor の Agent を TypeScript から呼び出せる Cursor SDK が発表されたので使ってみます。

料金

料金は標準のトークンベース従量課金に基づいて請求されます。
SDK 用の別課金というより、Cursor の通常のトークン従量課金として扱われます。

使えるモデルを確認する

Cursor.models.list() を実行すると、利用できるモデル一覧を取得できます。
実行して整形したものが以下です。

Model ID 表示名 主な指定可能パラメータ デフォルト
default Auto なし Auto
composer-2 Composer 2 fast fast=true
composer-1.5 Composer 1.5 なし なし
gpt-5.5 GPT-5.5 context, reasoning, fast context=1m, reasoning=medium, fast=false
gpt-5.4 GPT-5.4 context, reasoning, fast context=1m, reasoning=medium, fast=false
gpt-5.4-mini GPT-5.4 Mini reasoning reasoning=medium
gpt-5.4-nano GPT-5.4 Nano reasoning reasoning=medium
gpt-5.3-codex Codex 5.3 reasoning, fast reasoning=high, fast=true
gpt-5.3-codex-spark Codex 5.3 Spark reasoning reasoning=medium
gpt-5.2 GPT-5.2 reasoning, fast reasoning=high, fast=true
gpt-5.2-codex Codex 5.2 reasoning, fast reasoning=high, fast=true
gpt-5.1 GPT-5.1 reasoning reasoning=medium
gpt-5.1-codex-max Codex 5.1 Max reasoning, fast reasoning=high, fast=true
gpt-5.1-codex-mini Codex 5.1 Mini reasoning reasoning=medium
gpt-5-mini GPT-5 Mini なし なし
claude-opus-4-7 Opus 4.7 thinking, context, effort thinking=true, context=1m, effort=xhigh
claude-opus-4-6 Opus 4.6 thinking, context, effort, fast thinking=true, context=1m, effort=high, fast=false
claude-opus-4-5 Opus 4.5 thinking thinking=true
claude-sonnet-4-6 Sonnet 4.6 thinking, context, effort thinking=true, context=1m, effort=medium
claude-sonnet-4-5 Sonnet 4.5 thinking, context thinking=true, context=200k
claude-sonnet-4 Sonnet 4 thinking, context thinking=false, context=200k
claude-haiku-4-5 Haiku 4.5 thinking thinking=true
gemini-3.1-pro Gemini 3.1 Pro なし なし
gemini-3-flash Gemini 3 Flash なし なし
gemini-2.5-flash Gemini 2.5 Flash なし なし
grok-4-20 Grok 4.20 thinking thinking=true
kimi-k2.5 Kimi K2.5 なし なし

model.id には、Cursor SDK が返す id を指定します。

model: { id: "gemini-3-flash" }

各プロバイダが公開している model ID ではないので、注意してください。

API キーを作成する

Cursor SDK を使うには CURSOR_API_KEY が必要です。

Cursor Dashboard の Integrations & MCP から API キーを作成できます。

CleanShot 2026-04-30 at 17.03.22@2x

実際に使ってみる

手元のファイルを1つ読ませて、GitHub Issue に貼れる形へ整えるスクリプトを作ってみました。
なお今回使ったスクリプトは GitHub上から確認できます。
まず、簡単な障害ログを sample-notes.md として用意しました。

# 障害ログ

2026-04-30 09:12 JST から、チェックアウト画面で「注文を確定する」ボタンを押した一部のユーザーにエラーが表示されている。

- 影響範囲: `web-checkout` の本番環境
- 発生頻度: 直近30分で 42 件
- ユーザー影響: 注文確定に失敗する
- 直近の変更: 08:55 JST に `payment-service` v2026.04.30-1 をデプロイ

## ログ抜粋

```text
2026-04-30T09:12:44+09:00 web-checkout ERROR request_id=req_7f3a path=/api/checkout status=500
2026-04-30T09:12:44+09:00 payment-service ERROR request_id=req_7f3a provider=stripe message="idempotency key is required"
2026-04-30T09:12:45+09:00 web-checkout WARN request_id=req_7f3a retry_count=1 result=failed
```

## 補足

- 同じユーザーが再試行しても成功しないケースがある
- `payment-service` v2026.04.29-3 では同じエラーは確認できていない
- 返金や二重決済は今のところ報告なし

この内容を、Issue のテンプレートに近い形へ整えてもらいます。

実装の主要部分は以下です。

import { Agent, type SDKMessage } from "@cursor/sdk"

const apiKey = process.env.CURSOR_API_KEY

if (!apiKey) {
  throw new Error("CURSOR_API_KEY is required.")
}

const agent = await Agent.create({
  apiKey,
  name: "Cursor SDK first look",
  model: { id: process.env.CURSOR_MODEL ?? "gemini-3-flash" },
  local: {
    cwd: process.cwd(),
  },
})

const run = await agent.send(
 [
    "`sample-notes.md` の障害ログを読んで、GitHub Issue にそのまま貼れる形に整えてください。",
      "出力は日本語の Markdown にしてください。",
      "次の見出しを必ず含めてください。",
      "- 概要",
      "- 影響範囲",
      "- 発生時刻",
      "- 期待される挙動",
      "- 実際の挙動",
      "- 調査メモ",
  ].join("\n")
)

run.stream() で流れてくるイベントのうち、今回は tool_call と assistant のテキストだけ表示します。

function printEvent(event: SDKMessage) {
  if (event.type === "tool_call") {
    console.log(`\n[tool:${event.status}] ${event.name}`)
    return
  }

  if (event.type !== "assistant") {
    return
  }

  for (const block of event.message.content) {
    if (block.type === "text") {
      process.stdout.write(block.text)
    }
  }
}

依存関係を入れて実行します。

pnpm install
export CURSOR_API_KEY="crsr_..."
pnpm dev

実行すると、Agent が sample-notes.md を読むためにツールを呼び出していることが確認できました。

[tool:running] read

[tool:completed] read

最終的には、以下のような Markdown が返ってきました。

# 障害報告: チェックアウト画面での注文確定エラー

## 概要
チェックアウト画面において「注文を確定する」ボタンを押下した際、一部のユーザーで 500 エラーが発生し、注文が完了できない問題が発生しています。直近の `payment-service` のデプロイ(v2026.04.30-1)が原因である可能性が高いと考えられます。

## 影響範囲
- **対象環境**: `web-checkout` 本番環境
- **ユーザー影響**: 注文確定の失敗(再試行しても成功しないケースあり)
- **発生頻度**: 直近30分で 42 件

## 発生時刻
2026-04-30 09:12 JST 〜 継続中

## 期待される挙動
「注文を確定する」ボタンを押下後、正常に決済処理が行われ、注文完了画面が表示されること。

## 実際の挙動
ボタン押下時に 500 エラーが表示され、注文に失敗する。
ログを確認したところ、`payment-service` から `idempotency key is required` というエラーが返されている。

## 調査メモ
- **ログの状況**:
  - `web-checkout` でステータス 500 が発生。
  - `payment-service` (Stripe プロバイダー) にて `"idempotency key is required"` のエラーログを確認。
- **変更履歴との関連**:
  - 08:55 JST にデプロイされた `payment-service` v2026.04.30-1 以降で発生。
  - 前バージョン (v2026.04.29-3) では同様のエラーは確認されていない。
- **その他**:
  - 現時点で返金や二重決済の報告はなし。

また、macOS の Homebrew 環境では実行時に

Error initializing ignore mapping for .gitignore: Error: Ripgrep path not configured. ...

の warning が出ましたが、brew install ripgrep で解消できました。参考までに。

さいごに

Cursor SDK を使って、TypeScript から Cursor の Agent を起動してみました。
AI 系の SDK は Python メインのものが多い印象なので、TypeScript SDK として出てきたのは少し意外でした。
いろいろユースケースがありそうなので、次回はもう少し実際に使えそうなものを作ってみようと思います。
では👋

この記事をシェアする

関連記事