Cursor Agent SDK の使い方｜構成・コマンド・GitHub 連携を解説

Cursor Agent SDK で何ができるか

Cursor Agent SDK は、チームの業務に合わせたエージェントをコードで作り、テストして運用する仕組みです。PR のレビュー、変更内容に応じた担当者への振り分け、Issue の仕分けなどを、エージェントへの指示とプログラムの組み合わせで定義できます。

Cursor は公式の変更履歴で一般提供を発表しました。発表ブログでは、Bugbot などの自社エージェントを作るためのフレームワークだと説明しています。単にプロンプトを登録するだけでなく、指示、ツール、外部サービスとの連携、評価用テストを、通常のソフトウェアと同じように管理できる点が特徴です。

この記事では、公式の発表と現行ドキュメントをもとに、構成と導入時の判断材料を整理します。FIXIT による実機検証や運用実績の紹介ではありません。

指示とツールをプロジェクトで管理する

現行のプロジェクト構成の説明では、エージェントの定義を bot/ に置き、評価用テストをプロジェクト直下の evals/ に置きます。主なファイルとディレクトリは次のとおりです。

これらに加えて、サブエージェント、フック、スケジュールなどの定義も配置できます。「構成要素は 5 つだけ」と捉えるより、必要な機能を所定のディレクトリへ追加していくプロジェクトだと理解するとよいでしょう。

指示文やツールを変更したとき、コードと一緒に PR でレビューできます。自動処理に任せる範囲をチームで検討する際も、何を指示し、どの操作を許可したかをファイルで追えます。

FIXIT

設定画面で作るボットとは、何が違うの？

Tsukasa

指示もツールもファイルで管理します。変更を PR でレビューできるので、チームのルールを反映しやすい構成です。

CLI を導入してローカルで試す

現行ドキュメントでは、CLI の実行環境に Node.js 22.13 以上を指定しています。導入から開発サーバーの起動までは、次の流れです。

npm install --global @grok/agent-sdk
agent-sdk login
agent-sdk init ./my-bot
cd my-bot
agent-sdk dev

一般提供時の変更履歴には npx @cursor/agent-sdk init ./my-bot とありますが、現行ドキュメントでは @grok/agent-sdk のインストールを案内しています。導入コマンドは現行ドキュメントに合わせ、過去の告知にあるパッケージ名と混同しないようにしてください。

agent-sdk init はプロジェクトの雛形を作成し、agent-sdk dev はローカル開発用のサーバーとプレイグラウンドを起動します。ほかに、開発中によく使うコマンドをCLI リファレンスから挙げます。

info に想定したツールや連携が出ない場合は、ファイルの配置先や拡張子を見直します。指示文の調整だけで解決しようとせず、まずプロジェクトの定義が正しく読み込まれているかを確認します。

定義を読み込めたかを確認する

validate、info、eval は、それぞれ確認する対象が違います。validate は定義のエラーを調べ、info は読み込まれた構成を表示します。eval は、その構成で実行したエージェントの振る舞いを評価します。定義の検査に合格しただけでは、想定したツールを選び、指定した形式で返信するかまでは判断できません。

たとえば PR にコメントするツールを追加したのに、info の一覧に出ない場合は、指示文の書き方よりもファイル配置を先に調べます。公式の構成説明では、定義を発見するディレクトリや拡張子が決まっており、定義にエラーがある場合はサーバーの起動が拒否されます。

agent-sdk validate --dir .
agent-sdk info --dir .

変更をレビューするときも、指示文の差分と、読み込まれるツールの一覧を合わせて見ると、意図せず操作範囲を広げていないかを判断できます。ツールの一覧確認を、チーム側のレビュー手順に含める方法です。

GitHub や Slack のイベントから起動する

エージェントは、外部サービスで起きたイベントをきっかけに実行できます。一般提供時の変更履歴では、次の連携が紹介されています。

• GitHub・GitLab・Bitbucket の PR、コメント、CI のイベント
• Slack のメンションと DM
• 外部サービスからの webhook
• cron のスケジュール

GitHub のイベントを Cursor アカウント経由で受け取る場合は、公開 webhook URL が不要です。社内で webhook の受信サーバーを管理したくない場合に、検討できる方式です。

会話ごとにセッションがあり、メッセージとツール呼び出しの記録が残ります。PR や Slack のスレッドで追加の質問が来た場合は、同じセッションを再開します。

最初から複数の連携を有効にする必要はありません。たとえば PR レビューを目的にするなら、対象リポジトリと受け付けるイベントを絞り、想定した処理だけが実行されるかを確認してから対象を広げる方法があります。

eval とイベントの再現で、本番前に評価する

PR にコメントしたり、Issue を更新したりする処理は、指示文を読んだだけでは品質を判断できません。本番前に、どの入力で、どのツールが呼ばれ、どのような返信になるかをテストしてください。

Agent SDK の eval は、固定のメッセージを与え、ツール呼び出し、その入力、返信の形式などを検査する仕組みです。agent-sdk eval でローカルや CI から実行できます。

一般提供時の告知では、agent-sdk github replay <pr-url> も紹介されています。実際の PR から webhook のペイロードを生成し、イベントを再現する機能です。--dry-run --fixtures-dir fixtures/ を付けると、ペイロードを評価用テストのデータとして保存できます。

FIXIT

テストが通れば、PR のレビューを全部任せられる？

Tsukasa

テストで確認した範囲までです。呼び出すツールと入力、返信を検査し、人が判断する処理は分けておきます。

正常な処理だけでなく、判断材料が不足する PR や、書き込みを許可しないケースも評価対象に含めることを勧めます。自動処理の成功例だけを揃えると、停止や人への引き継ぎが必要な場面を見落としやすくなるためです。

評価中の書き込みを防ぐ

公式の eval ガイドでは、eval が実際のツールを実行すると説明しています。評価用の PR データを保存しただけでは、PR への投稿や外部システムの更新を防げません。評価用の入力と、外部への書き込みを止める実装は、別々に用意してください。

公式の方法は、書き込みを行うツール内でセッションの ctx.session.purpose を確認するものです。値が "eval" の場合は、外部への投稿を実行せず、判定結果だけを返します。ツールを呼び出した記録は残るため、「投稿するツールを選んだか」と「実際に投稿したか」を分けて検査できます。

読み取り用のツールで PR の内容を取得し、投稿用のツールでコメントを書き込む設計なら、投稿用のツールにこの分岐を置きます。指示文に「テスト中は投稿しない」と書くだけで済ませず、外部サービスを更新する直前のコードで止める方法です。

過去の PR を評価ケースにする

評価用テストのファイルは、プロジェクト直下の evals/ に置きます。eval リファレンスによると、拡張子は .eval.ts または .eval.js で、evals/evals.config.ts に同時実行数の maxConcurrency を設定します。過去の PR を使う場合も、何を合格条件にするかはチーム側で定義します。

PR レビューを想定した、FIXIT の評価項目の例を示します。以下は SDK に組み込まれた業務ルールではありません。

ツール呼び出しは t.calledTool、呼び出していないことは t.notCalledTool で検査できます。返信を JSON で受け取る設計なら、必要なキーや型が揃っているかも評価対象です。「処理が終了した」ことだけでなく、業務として任せたい判断を検査項目にしてください。

実行結果には、入力、検査結果、ツール呼び出し、最終的な返信などが残ります。失敗した場合は、入力の読み取り、ツールの選択、返信の内容を分けて調べられます。まず重要なケースにタグを付けて PR で実行し、広いケース群は定期実行する運用も、公式ガイドで紹介されています。

デプロイ先とチームの権限を選ぶ

実行場所は、Cursor 管理のホスティングか、自前のインフラです。デプロイのドキュメントによると、agent-sdk deploy は push 済みの Git ref をビルドします。未コミットの変更はデプロイに含まれません。

Cursor 管理のホスティングを使うには、チームで agent hosting が有効になっている必要があります。CLI リファレンスでは、エージェントへのアクセス権を持つチームのサービスアカウントキーからもデプロイできると説明しています。

デプロイ後のアクセス権は、公式の権限表では次の 3 段階です。

自前で実行する場合は、Node.js のプロセスとして運用でき、コンテナにもまとめられます。公式のデプロイ手順では、外部公開前の TLS や認証、状態を保存する領域、スケジュールの重複実行を防ぐ設定なども扱っています。ホスティングを自前にする判断には、実行場所だけでなく、こうした運用の担当も含める必要があります。

送信先とシークレットを定義する

管理画面のアクセス権に加えて、エージェントから接続する外部サービスも整理します。デプロイのドキュメントでは、hosting.egressDomains に接続先のホスト名を、hosting.secretNames に使うシークレットの名前を定義します。プロジェクトには名前をコミットし、API キーなどの値はコミットしません。

接続先は、スキームやパスを含めず、小文字のホスト名で指定します。さらに、チームの外向き通信のポリシーも適用されるため、エージェント側に接続先を書いただけで許可されるとは限りません。デプロイ時に許可されていないホストのエラーが出たら、チーム管理者に許可を依頼するか、接続先を見直します。

シークレットの値は、デプロイ後に agent-sdk secret set の非表示の入力欄で設定します。コマンドの引数に NAME=VALUE の形で値を含める方法は、公式には使わないよう案内されています。また、ホスティング環境の値が届くのはモジュールの読み込み後なので、実際に使うツールやハンドラーの中で参照します。ローカルの環境変数では読めても、ホスティングでは同じタイミングで読めるとは限らない点に注意してください。

チームでのレビューでは、接続先、必要なキーの名前、そのキーで許可する操作を一緒に提示すると、管理者が必要な権限を判断しやすくなります。キーの値をレビュー資料に貼る必要はありません。

本番の更新と稼働確認を分ける

本番の更新では、どのリポジトリの、どの Git ref を動かすかを明確にします。複数のエージェントを同じリポジトリで管理する場合は、対象のディレクトリと識別用の slug も合わせて確認します。手元の未コミットの変更で試験が通っても、push 済みの内容に入っていなければ本番には反映されません。

デプロイ後は、agent-sdk deployment get <slug> で状態を取得できます。ホスティング上のセッションを始めるコマンドは session create で、--wait を付けるとセッションが開始するまで待ちます。session get や logs で処理の記録を読む工程と、デプロイ自体が成功したかを見る工程を分けてください。

GitHub などの複数のリポジトリからイベントを受け取る場合は、再デプロイ時の設定にも注意が必要です。公式ドキュメントでは、監視対象のリポジトリ一覧は再デプロイのたびに置き換わるため、--cursor-events-repo を使う場合は必要なリポジトリを毎回すべて指定すると説明しています。追加するリポジトリだけを書けば、前の一覧に追記される仕組みではありません。

運用開始前に、指示やツールを変更する担当、デプロイする担当、シークレットを更新する担当を決めておくことを勧めます。自動処理のコードと、実際に稼働している設定の両方を追える状態にするためです。

料金と利用上限は、分けて確認する

一般提供時の変更履歴には、SDK 固有の料金表や全プランの利用条件は載っていません。通常の Cursor の契約だけで、必要なホスティングと利用量をすべて賄えるとは判断できません。導入前には、チームで使える機能と、モデル利用・ホスティングの課金条件を分けて確認してください。

利用上限については、現行のLimits ページに記載があります。一部のチームに上限があり、その場合の既定値は次のとおりです。

これはすべてのチームに同じ上限が適用されるという説明ではありません。また、モデルのトークン数や実行回数の上限とも別です。自社の契約に適用される条件を、管理者または提供元に確認してください。

TypeScript SDK との使い分け

Cursor には、TypeScript のプログラムからエージェントを呼び出す @cursor/sdk もあります。公式の発表ブログでは、Agent.create でエージェントを作り、ローカルまたは Cursor のクラウドで実行するライブラリとして紹介されています。

現行の Agent SDK ドキュメントは、Agent SDK が Cursor SDK の実行基盤を利用すると説明しています。両者を無関係な SDK と捉えるのは適切ではありません。

使い分けを検討するなら、既存の TypeScript アプリケーションからエージェントを呼び出したいのか、イベントを受け付けて継続的に処理するエージェントをプロジェクトとして管理したいのかを、先に整理するとよいでしょう。

まとめ

Cursor Agent SDK では、指示、ツール、外部連携、評価用テストをコードで管理できます。PR や Slack のイベントなどから起動し、Cursor 管理のホスティングと自前の環境を選べます。

まずは対象業務を 1 つに絞り、ローカルで作成・評価してからデプロイを検討してください。導入コマンドは現行ドキュメントに合わせ、チームの権限、利用上限、課金条件を運用開始前に確認します。

チームでの設計や運用を相談したい場合は、AI エージェント開発 や AI 開発ツール定着支援 をご覧ください。具体的な検討事項は、お問い合わせ からご相談いただけます。

Cursor の関連する更新は、Cursor Origin とクラウドエージェントのイベント駆動化 や Cursor Remote Control の使い方 にまとめています。