
Cursor SDK が発表されたので使ってみる
リテールアプリ共創部の末永です。
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 キーを作成できます。

実際に使ってみる
手元のファイルを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 として出てきたのは少し意外でした。
いろいろユースケースがありそうなので、次回はもう少し実際に使えそうなものを作ってみようと思います。
では👋









