Cursor Agent SDKとは｜使い方とデプロイ手順

「Cursor Agent SDK が一般提供になったらしいが、Automations と何が違うのか」「書いてあるコマンドを打ったのに動かない」——新しい仕組みが出た直後は、公式の発表と手元の結果が合わず手が止まりがちです。

結論から言うと、Cursor Agent SDK はエージェントを1つのフォルダ（Markdown と TypeScript）として書き、手元で試し、eval で振る舞いを検査してから Cursor の上か自前のサーバーに置くための道具です。2026年10月29日時点で、発表文にある npx @cursor/agent-sdk は npm に見つからず、公式 docs が案内する @grok/agent-sdk を入れるのが正しい入口です。

株式会社Fyveは、Mac mini 1台で毎日3回の記事作成ジョブを無人で回しています。この記事では、公式の changelog・docs・npm を一次情報として読み、私たちが自前の定期実行で後から足してきた守りと比べながら、Agent SDK の中身と始め方、引っかかりやすい点を整理します。なお、私たちは Agent SDK をまだ手元で動かしていません。書くのは公式に書かれていることと、自前の運用から言えることだけです。

Cursor Agent SDK とは：エージェントを「コードの1プロジェクト」として持つ仕組み

Cursor は 2026年10月20日の changelog で Agent SDK の一般提供を発表しました。説明は「エージェントをコードのフォルダとして定義し、eval で試し、Cursor か自分のインフラにデプロイできる」というものです。

公式 docs によると、Agent SDK は Bugbot・Security Review・Approval Bot・Rollouts を動かしているのと同じ「Cursor SDK のハーネス」を使っています。Cursor が自社のボットで使っている土台を、利用者にも開いた形です。

Automations・Grok Bot との違い

Cursor にはすでに、管理画面で作る Automations と、コードを書かずに話しかけて使う Grok Bot があります。docs は3つを次のように分けています。

判断の目安は単純です。プロンプトと起動のきっかけを変えるだけなら Automations で足ります。道具の入出力を型で決めたい、変更をプルリクエストでレビューしたい、振る舞いを自動テストで守りたい、という段階になったら Agent SDK です。docs には Automation を Agent SDK のプロジェクトに変換する agent-sdk init --from automation:<URL> も用意されています。

Cursor Agent SDK のフォルダ構成：置いた場所で役割が決まる

Agent SDK のいちばんの特徴は、ファイルを置く場所がそのまま設定になることです。エージェントの中身は bot/ の下に置き、eval はその横の evals/ に置きます。

主なフォルダの役割は次のとおりです（docs「Project layout」より）。

置き場所を間違えたファイルは黙って無視されます。docs は「info に道具やチャネルが出てこなければ、置き場所か拡張子が違う」と書いています。agent-sdk validate --dir . で不備を確かめ、agent-sdk info --dir . で「実際に見つかったもの」を一覧してから先へ進むのが安全です。

読み込まれる場所が決まっている仕組みほど、書いたものではなく、読み込まれたものを一覧で確かめる手順を最初に入れておくと、後の切り分けが速くなります。info --json は、動いているサーバーの GET /v1/info と同じ形で出るので、CI で「道具の数が減っていないか」を見張る使い方もできます。

モデルは agent.ts の model で、Cursor で使えるモデルから指定します。docs の agent-config によると、指定しなければ grok-4.5（effort=high・fast=true）が使われます。子のエージェントは指定を省くと親のモデルを引き継ぎます。

この記事を読んでいるあなたへ無料プレゼントClaude Codeを「素のまま」使うな設定で差がつく——CLAUDE.md・権限・スキルの実物を公開（全24ページ）

そのまま書き換えて使えるCLAUDE.mdの型お金と送信をAIに触らせない「3段階の柵」1回教えたら何度でも動く、手順書のコピペ雛形

無料でダウンロード

中身のプレビューを見る ↓登録すると、過去の特典もまとめて受け取れます（PDF 19点・合計499ページ ＋ すぐ使えるzip素材 3点）

起動のきっかけは5種類：GitHub・Slack・webhook・cron・リマインダー

changelog と docs によると、エージェントは次の出来事で起きます。

• コードの置き場の出来事：GitHub・GitLab・Bitbucket のプルリクエスト、コメント、CI。GitHub の出来事は Cursor のアカウント経由で届くため、公開の webhook URL を用意しなくてよい
• Slack：メンション・DM・見張っているチャンネルへの投稿。同じスレッドでの返信は同じ会話として続く
• webhook：任意のサービスからの通知
• cron：bot/schedules/ に置いた定時の仕事
• リマインダー：会話の途中で「2時間後に CI を見直す」のように自分で予約する、会話ごとの起こし直し

会話ごとに独立したセッションが作られ、メッセージと道具の呼び出しがすべて記録されます。プルリクエストや Slack のスレッドで追いかけて話しかけると、同じセッションが再開します。

注意点が1つあります。GitHub を Cursor アカウント経由で受けるときに届くのは、プルリクエストとコメントの出来事です。docs の Automation 変換ガイドは「push・issue・CI のきっかけには、GitHub App か github forward による webhook 配信が要る」と書いています。CI の失敗で起こしたい場合は、この配線を先に確認してください。

Cursor Agent SDK の使い方：インストールから手元で動かすまで

パッケージ名に注意：@cursor/agent-sdk ではなく @grok/agent-sdk

ここがいちばん引っかかりやすいところです。10月20日の changelog は npx @cursor/agent-sdk init ./my-bot と案内しています。ところが2026年10月29日に npm を確認すると、@cursor/agent-sdk というパッケージは見つかりませんでした（Not found）。

公式 docs の Agent SDK のページは、インストールを npm install --global @grok/agent-sdk と書き、「パッケージは以前 @cursor/bdk だった」と添えています。npm 上でも @grok/agent-sdk が存在し、同日時点の最新は 0.5.0（10月28日 UTC 公開）、必要な Node は 22.13 以上です。changelog のコマンドが通らなかったら、docs の入れ方に切り替えてください。

Web 検索の要約には、逆に「@grok/agent-sdk は Cursor の資料と合わないので信頼できない」と答えるものもありました。発表直後は、発表文・docs・パッケージの置き場の3つが揃っていないことがよくあります。名前が食い違ったら、実際にパッケージが置かれている場所（npm）と、いま公式 docs が書いている手順の2つで決めるのが確実です。

最初の5手

npm install --global @grok/agent-sdk   # Node 22.13 以上
agent-sdk login                          # ブラウザで Cursor にサインイン
agent-sdk init ./my-bot                  # ひな形を作る
cd my-bot
agent-sdk dev                            # 手元でプレイグラウンドつきで起動

別のターミナルで agent-sdk run --dir . --message "Introduce yourself in one sentence." を打ち、返事が返れば土台は動いています。

init には --template でひな形を選ぶ指定があり、docs の CLI リファレンスには agentic-owners・security-reviewer・triage-linear・triage-jira などが並んでいます。セキュリティのレビュー役や、Linear・Jira の振り分け役から始められます。

docs は、コーディングエージェントに作らせる手順も用意しています。案内のプロンプトを Claude Code や Cursor に貼ると、CLI を入れ、用途を質問し、同梱の bdk-create-agent スキルに沿ってひな形を作るところまで進みます。

道具は「モデル抜き」で先に試す

docs の公式チュートリアル（PR のレビュー役）で、私たちがいちばん良いと思ったのはこの順番です。

1. 道具（tools/inspect_pr.ts）を書く
2. agent-sdk tool call inspect_pr --dir . --input '{...}' で、モデルを通さずに道具だけを呼んで結果を確かめる
3. 道具が正しい材料を返すようになってから、指示（instructions.md）を整える

docs も「指示を調整する前に道具を確かめる」と明記しています。答えがおかしいとき、原因は指示の書き方より、道具が渡している材料の側にあることが多いからです。私たちの記事作成ジョブでも、品質の問題を追うと「書き手の AI に渡していた規範のファイルが足りなかった」という材料側の原因に行き着いたことがありました。

eval で「どの道具を呼んだか」を検査する

eval は、決まった入力をエージェントに送り、どの道具が、どんな入力で呼ばれ、返事がどんな形だったかを確かめる仕組みです。docs の例は次のようなものです。

// evals/readiness.eval.ts
import { defineEval, includes } from "@grok/agent-sdk/evals";

export default defineEval({
  tags: ["smoke"],
  async test(t) {
    await t.send("Is https://github.com/acme/checkout/pull/42 ready to approve?");
    t.succeeded();
    t.calledTool("inspect_pr");      // 調べる道具を呼んだか
    t.notCalledTool("approve_pr");   // 承認の道具は呼んでいないか
    t.check(t.reply, includes(/ready|blocked|approve/i));
  },
});

文章の良し悪しではなく、行動を検査しているのがポイントです。「調べてから判断したか」「やってはいけない操作をしていないか」を固定の入力で確かめられます。意味の正しさを見たい場合は、判定役のモデル（judge）を使う書き方も用意されています。実行は agent-sdk eval --dir . --tag smoke で、手元でも CI でも回せます。

eval は本物の道具を動かす：書き込みを止める一行

docs は「eval は本物の道具を動かす」と注意しています。レビューを投稿する道具なら、eval のたびに本当に投稿されてしまいます。そこで、eval のセッションには purpose: "eval" が付くので、書き込む道具の中でそれを見て、外部への操作をせずに判断だけ返すように書きます。

async execute({ findings }, ctx) {
  if (ctx.session.purpose === "eval") {
    return { posted: false, reason: "eval", count: findings.length };
  }
  // ここから先が本番の書き込み
}

私たちの運用から：検査は「後から足す」と穴が空く

私たちの記事作成ジョブは、書いた記事を公開する前に、執筆とは別のプロセスで動く AI の監査官に検査させ、通ったものだけを公開しています。この検査項目は最初から揃っていたわけではありません。2026年7月には、文字の入っていないサムネイルが監査を通ってしまう事故があり、画像の検査を「軽微な指摘」から「1件でも不合格」に格上げしました。

この経験から言えるのは、検査は事故のたびに足すと、足すまでの間が必ず穴になるということです。Agent SDK の eval が「道具を呼んだか・呼んでいないか」を最初から書ける形になっているのは、この穴を先に塞ぐ設計だと受け取りました。PR の承認や外部への投稿のように取り返しのつかない操作を持つエージェントほど、最初の1本の eval に notCalledTool を入れておく価値があります。

デプロイ：Cursor の上に置くか、自分で動かすか

Cursor のホスティングに置く

agent-sdk login
agent-sdk validate
agent-sdk deploy

deploy は動き出すまで待ち、URL を表示します。管理は Cursor の Deployed Agents の画面で行います。docs が強調している点は次のとおりです。

• Git に push した版がデプロイされる。手元のコミットしていない変更は載らない
• 通信先は宣言した宛先だけ。agent.ts の hosting.egressDomains に書いたホストにしか出られない。チームの方針で禁止された宛先を書くと deploy が失敗し、エラーにそのホスト名が出る
• 秘密情報は名前だけをコミットする。値は agent-sdk secret set <slug> <名前> で登録し、次の処理から再デプロイなしで使われる
• 秘密情報はモジュールの読み込み後に届く。だから、使う処理（ハンドラ・道具）の中で読む
• 残るのはセッションと ctx.host.kv・ctx.host.files だけ。それ以外にディスクへ書いたものは、再起動や再デプロイで消えうる
• Cursor の「Privacy Mode (Legacy)」のままだと、デプロイ・ホストでのセッション・eval の実行は拒否される。新しい Privacy Mode に切り替えるか、チームの管理者に頼む

私たちの運用から：秘密情報が「子のプロセスに届かない」事故

「秘密情報は使う処理の中で読む」という一文は、私たちにとって身に覚えのある話です。私たちの記事作成ジョブは、監査のために AI をもう1つ別プロセスで起動します。その入れ子のプロセスには、親が持っている認証情報が引き継がれていませんでした。

しばらくは別の場所に保存されたログイン状態がたまたま効いていたため気づかず、2026年8月12日にそれが期限切れになってから、25回連続で監査が「判定不能」になり、全部が下書きに退避されました。今は、監査を起動する直前に毎回設定ファイルを読み直す形にしています。

Agent SDK のホスティングは、秘密情報の名前を先に宣言させ、値は管理画面かコマンドで別に入れ、読むタイミングまで決めています。自前の構成で私たちが事故のあとに足した決まりが、最初から手順として並んでいる形です。

自分のサーバーで動かす

自前で動かす場合は agent-sdk serve を使います。docs の条件は、Node 22.13 以上（Bun は不可）、CURSOR_API_KEY の設定、--bearer-token による認証、--state-root をリポジトリの外のバックアップされる場所に置くこと、TLS か認証つきのプロキシを前に置くこと、です。1つのプロセスで、あるディレクトリの下の全エージェントを配信できます。

自前で動かしても、モデルを呼ぶ部分は Cursor の資格情報を使います。docs によると、Cursor の資格情報が要るのは run と eval で、CLI は --api-key・CURSOR_API_KEY・CURSOR_API_KEY_FILE・CURSOR_SERVICE_ACCOUNT_KEY・agent-sdk login で保存したもの、の順に探します。

スケジュール（cron）の注意点：時刻は UTC、1回は26分まで

定時の仕事は bot/schedules/ に置きます。いちばん簡単なのは、frontmatter に cron: を書いた Markdown ファイルです。本文がそのままプロンプトになり、追いかけの会話なしで最後まで実行されます。

---
cron: "0 9 * * 1-5"
---
Pull open incidents and post a summary to the metrics endpoint.

docs の決まりで、日本から使うときに特に効くのは次の点です。

• cron は UTC で書く（5項目・分単位）。日本時間（JST）は UTC より9時間進んでいる
• Cursor のホスティングでは、run ハンドラは26分以内に終える必要がある（receive・waitUntil に渡した仕事も含む）
• 1つの予定時刻につき実行は1回まで。止めたデプロイでは、その時刻の実行は飛ばされる
• 1回のデプロイに置けるスケジュールは最大64個
• 前回の実行のメモリは次に引き継がれない。状態は ctx.host.kv か ctx.host.files に置く
• 開発用の agent-sdk dev ではスケジュールは自動で動かない。手で起こして試す

私たちの記事作成ジョブは、日本時間の 06:00・14:00・22:00 に起動しています。これを Agent SDK の cron に直すと次のようになります。

最後の行が落とし穴です。日本の朝9時より前は UTC では前日になるため、曜日の指定も1日ずれます。「平日の朝8時」をそのまま 1-5 で書くと、日本時間の火曜〜土曜の朝に動いてしまいます。

もう1つは26分の上限です。私たちのジョブは、調査・執筆・画像の生成・監査・公開までを1回で行うため、26分には収まりません。Agent SDK に移すなら、1つのスケジュールで全部をやらせず、receive で仕事を渡して段に分けるか、長い処理は自前の serve 側に残す設計になります。

Cursor Agent SDK の料金と使える条件

2026年10月29日時点で、changelog にも Agent SDK の docs にも、Agent SDK 専用の料金や、使えるプランの記載は見当たりませんでした。推測で書くのはやめておきます。docs から読み取れるのは次の範囲です。

• モデルを動かす run・eval には Cursor のログイン（資格情報）が要る
• CLI に session list --view cost・session get --view cost があり、セッションごとのコストを見られる（手元で動かしているときに限る項目がある）
• Cursor のホスティングを使うには、Privacy Mode (Legacy) ではないこと
• Deployed Agents の権限は閲覧者（Viewer）・編集者（Editor）・所有者（Owner）の3段階で、チームでの共有を前提にしている

導入を決める前に、Cursor の料金ページと契約中のプランの管理画面で、モデル利用とホスティングの扱いを確認してください。

私たちの見方：Cursor Agent SDK を入れるべき人・まだ早い人

入れてよい人

• PR のレビュー・振り分け・承認をボットに任せたいチーム。GitHub の出来事を公開 URL なしで受けられ、github replay で本物の PR を使った再現テストができる。手元で同じことを組むより配線が少ない
• Slack で答える社内ボットを作りたいチーム。スレッドごとの会話の継続、途中経過の表示の仕方まで、設定で選べる
• Automations で始めた仕事が育ってきた人。変換コマンドがあり、プロンプトだけの運用からコードとテストの運用へ段階的に移れる

まだ早い人

• 1回の処理が26分を超える定時の仕事をそのまま載せたい人。分けて作り直す前提になる
• 料金を確定させてから始めたい人。上のとおり、専用の料金の記載がまだ見当たらない
• Cursor を通さずに、自分で契約したモデルの API で動かしたい人。docs の書き方では、モデルは Cursor のモデルから選び、run・eval には Cursor の資格情報が要る

私たち自身は、今の記事作成ジョブをすぐに移すことはしません。1回の処理が長いことと、Mac mini 1台の自前の構成で、書き込み先の制限や公開前の監査をすでに回せているからです。ただ、通信先・秘密情報・状態の置き場・検査を最初に宣言させるという Agent SDK の作りは、自前で組む人にとっても良いチェックリストになります。自分の定期実行に、この6項目（起動・1回の上限・秘密情報・通信先・検品・状態の保存）を当てはめて、空欄になっているところがないかを見てみてください。

自前で定期実行を組む方法は、次の記事で詳しく書いています。

Claude CodeMac miniをAI自動化サーバーにする｜claude -p×launchdで定期実行を集約

Claude Code 側の定期実行の選択肢は、こちらで比べています。

Claude CodeClaude Code定期実行の完全比較｜/loop・cron・routinesの使い分け

Cursor そのものの使い方から押さえたい方は、こちらからどうぞ。

Claude CodeCursorの使い方｜初心者の導入から実務活用まで完全解説

まとめ：Cursor Agent SDK は「決まりを先に書かせる」エージェントの器

• Cursor Agent SDK は、エージェントを bot/ の下のフォルダとして書き、eval で検査し、Cursor か自前のサーバーに置く仕組み（2026年10月20日 一般提供）
• 2026年10月29日時点で、入れるパッケージは @grok/agent-sdk（最新 0.5.0・Node 22.13 以上）。changelog の @cursor/agent-sdk は npm に見つからない
• 起動のきっかけは GitHub など・Slack・webhook・cron・リマインダー。cron は UTC で書き、日本の朝9時より前は曜日もずれる
• eval は文章ではなく「どの道具を呼んだか」を検査する。書き込む道具は purpose: "eval" で止める
• ホスティングでは、通信先・秘密情報の名前・状態の置き場を宣言する。1回の定時の処理は26分まで
• 専用の料金・使えるプランは、changelog と docs には見当たらない。契約前に公式で確認する

株式会社Fyveは、自前の構成で無人のジョブを毎日回しながら、新しい仕組みが出るたびに「今の運用のどこを置き換えられるか」を確かめています。Agent SDK は手元で動かした段階で、気づいたことをこの記事に足していきます。