室谷代表取締役Cursor SDK 1.0.31は、Cursorが公開したSDKの更新で、実行中のエージェントを軌道修正したり、バックグラウンドで動くサブエージェントの結果を受け取ったりできるようになったんですよね。地味に見えて、エージェントを実運用に組み込んでいる人ほど効いてくる内容です。
テキトー教師DotAI 認定講師そうなんですよ。今回は4つの機能がまとめて入っていて、単に「便利になった」という話じゃなくて、これまでエージェントに長いタスクを任せられなかった理由が一つずつ潰されているんです。
まず何が発表されたかを整理しましょう。
まず何が発表されたかを整理しましょう。
室谷代表取締役発表はCursorの公式Xアカウントと公式ドキュメントのチェンジログから出ています。内容は、
run.steer()による実行中の軌道修正、バックグラウンドサブエージェントの結果が親に返る変更、カスタムツールへのMCPアノテーション付与、そしてsystemPromptによるCursor組み込みプロンプトの置き換えの4点です。テキトー教師DotAI 認定講師ここで大事なのは、4つとも対応範囲が同じではないという点なんですよ。そこを混ぜてしまうと「試したけど動かない」になりがちなので、後半で言語別に丁寧に分けますね。
Cursor SDK 1.0.31とは？今回追加された4つの新機能
Cursor SDK 1.0.31で追加された4つの新機能
run.steer(text)
実行中のターンにメッセージを注入する
バックグラウンドサブエージェント
結果が親にフォローアップターンとして返る
MCPアノテーション
readOnlyHintやdestructiveHintなどでカスタムツールの性質をモデルに伝える
systemPrompt
Agent.create()のsystemPromptでCursor組み込みのシステムプロンプトを自前のものに置き換える
室谷代表取締役そもそもCursor SDK自体の立ち位置を確認しておくと、これはCursor IDEやCLI、Webで動くコーディングエージェントを、自分のコードから呼び出せるようにするパッケージです。TypeScript版が
@cursor/sdk、Python版がcursor-sdkで、1.0.24以降は両者が同じバージョン番号で同時にリリースされています。テキトー教師DotAI 認定講師講座でもよく聞かれるんですが、Cursor IDEのエージェントとSDKのエージェントは別物ではなくて、同じエージェントをスクリプトから動かすための入口なんですよ。だからCIに組み込んだり、バックエンドから呼んだり、社内ツールに埋め込んだりという使い方ができます。
Cursor IDEそのものについてはCursorとは？マウスカーソルからAIエディタまで徹底解説でも整理しているので、あわせて読むと全体像がつかみやすいです。
Cursor IDEそのものについてはCursorとは？マウスカーソルからAIエディタまで徹底解説でも整理しているので、あわせて読むと全体像がつかみやすいです。
室谷代表取締役その上で今回の1.0.31です。追加されたのは、実行中にメッセージを差し込める
run.steer(text)、バックグラウンドサブエージェントの結果が同一ラン上のフォローアップターンとして親に返る変更、カスタムツールにreadOnlyHintやdestructiveHintといったMCPアノテーションを付けられるようにする変更、そしてAgent.create()のsystemPromptでCursor組み込みのシステムプロンプトを置き換えられる変更です。テキトー教師DotAI 認定講師整理するとこうです。
run.steer(text)：実行中のターンにメッセージを注入する- バックグラウンドサブエージェント：結果が親にフォローアップターンとして返る
- MCPアノテーション：カスタムツールの性質をモデルに伝える
systemPrompt：Cursor組み込みのシステムプロンプトを自前のものに置き換える
室谷代表取締役この4つ、実は全部「エージェントに任せられる仕事の範囲を広げる」方向に効いていて。特にバックグラウンドの結果が消えなくなったのは、MYUUUでもエージェントを並列で走らせるときに効いてくるタイプの変更だなと感じています。
run.steer()とは？実行中エージェントを軌道修正する仕組み
run.steer() の戻り値による分岐
今のターンにメッセージを注入できたか？
YES ／ complete_delivered
- 進行中のターンにメッセージが注入される
- 呼び出し側は戻り値を見てそのまま続行
NO ／ revert_to_followup
- 今のターンには注入されない
- 通常のフォローアップとして送り直す
- クラウドランではこちらが返る
室谷代表取締役run.steer()は、実行中のランに対してメッセージを次のターンへ注入するAPIです。公式の説明では、run.steer(text)が進行中のターンにメッセージを注入し、complete_deliveredを返すか、通常のフォローアップとして送るべき場合にはrevert_to_followupを返す、という挙動になっています。テキトー教師DotAI 認定講師ここが一番おもしろいところで、
steer()は必ず差し込めるわけではなくて、「今のターンに注入できたよ」というcomplete_deliveredと、「これは普通のフォローアップとして送り直してね」というrevert_to_followupの2つの結果を返すんですよ。つまり呼び出し側が戻り値を見て分岐する設計になっています。室谷代表取締役そうなんですよね。だから「steerしたつもりが実は届いていなかった」を防げる。
戻り値を見ずに投げっぱなしにする実装は避けたほうがいいと思います。
戻り値を見ずに投げっぱなしにする実装は避けたほうがいいと思います。
テキトー教師DotAI 認定講師もう一つ重要なのが、前景でサブエージェントが動いている最中に
steer()を呼ぶと、そのサブエージェントがバックグラウンドに移って作業を続けるという点です。ここが今回の発表で一番おもしろい連動で、軌道修正しつつ、走っているサブタスクは殺さずに続けられるわけです。室谷代表取締役これ、実際にエージェントを長時間走らせていると「あ、この方向じゃない」と思う瞬間が必ずあるんですよ。そこで止めて最初からやり直すと、それまでの作業が全部無駄になる。
それが
それが
steer()で方向だけ変えられるなら、コストも時間もかなり変わってきます。テキトー教師DotAI 認定講師ただし対応範囲には制限があって、steeringはTypeScriptのローカルラン限定です。クラウドランでは
ここは覚えておきたいところですね。
revert_to_followupが返る、と公式に書かれています。ここは覚えておきたいところですね。
室谷代表取締役あと、以前の挙動として「修正したいときは普通のフォローアップとして送り直すしかなかった」という説明をしたくなるところですが、これは資料で明示されている話ではないので、そこは推測として置いておきましょう。確実に言えるのは、
revert_to_followupが返ったときは通常のフォローアップとして送る、という現在の仕様です。バックグラウンドサブエージェントの結果が親に返るようになった
バックグラウンド結果回収とsteeringの対応範囲
| 機能 | TypeScript | Python |
|---|---|---|
| バックグラウンド結果の回収 | ○ | ○ |
| steering | ○ | × |
| システムプロンプト | ○ | × |
室谷代表取締役2つ目が、バックグラウンドサブエージェントの結果が親に返るようになった変更です。エージェントがサブエージェントをバックグラウンドで走らせたとき、その結果が親ターンの終了時に破棄されるのではなく、同一ラン上のフォローアップターンとして親に返るようになりました。
テキトー教師DotAI 認定講師これは実務的にかなり大きいんですよ。
つまり呼び出し側から見ると、サブエージェントの完了まで待てる一貫したストリームになるわけです。
run.stream()がそれらのターンを通して流し続けて、run.wait()はそれらが終わった後に解決する、という説明になっています。つまり呼び出し側から見ると、サブエージェントの完了まで待てる一貫したストリームになるわけです。
室谷代表取締役以前はサブエージェントをバックグラウンドで動かすと、親ターンが終わった時点で結果が破棄されていた、と。だから複雑なタスクを任せられない直接の障壁になっていたんですよね。
テキトー教師DotAI 認定講師講座で受講生さんがエージェントを並列化しようとして詰まるポイントがまさにここで、「バックグラウンドに投げたはいいけど結果が返ってこない」という状態だと、結局は逐次実行に戻さざるを得ないんですよ。それが解消される意味は大きいです。
室谷代表取締役しかもこれ、TypeScriptとPythonの両方のローカルエージェントで使えるんですよね。steeringがTypeScript限定なのに対して、こちらはPythonでも効く。
Pythonでエージェントを組んでいる人には朗報だと思います。
Pythonでエージェントを組んでいる人には朗報だと思います。
テキトー教師DotAI 認定講師整理すると、バックグラウンド結果の回収はローカルのTypeScriptとPython、steeringとシステムプロンプトはTypeScriptローカル限定、という切り分けです。この違いは実装前に必ず確認したほうがいいですね。
MCPアノテーションで危険なツール呼び出しを事前判別できる
室谷代表取締役3つ目が、カスタムツールにMCPアノテーションを付けられるようになった変更です。
local.customToolsのエントリにannotationsを付けると、title、readOnlyHint、destructiveHint、idempotentHint、openWorldHintといったMCPのツールアノテーションがモデルに渡されます。テキトー教師DotAI 認定講師これは「参照」と「削除」をモデルが呼び出し前に区別できるようになる、というのがポイントです。
readOnlyHintが付いていれば読み取り専用、destructiveHintが付いていれば破壊的、というシグナルになるわけですね。室谷代表取締役エージェントにツールを渡すとき、一番怖いのが破壊的な操作をいきなり呼ばれることなんですよ。事前に性質が伝わっていれば、モデル側の判断材料が増える。
地味ですけど、安全性の設計としては効いてきます。
地味ですけど、安全性の設計としては効いてきます。
テキトー教師DotAI 認定講師ただしここは誤解されやすいんですが、公式の説明ではこれらのアノテーションは「記述的なヒント」であって、SDKは強制しないと明記されています。つまり
あくまでモデルに伝わる情報が増える、という話です。
destructiveHintを付けたからといって、そのツールの実行がブロックされるわけではないんですよ。あくまでモデルに伝わる情報が増える、という話です。
室谷代表取締役そうなんですよね。だから実際に危険な操作を止めたいなら、別途フックやサンドボックスの設定と組み合わせる必要がある。
アノテーションは「モデルに文脈を与える」レイヤーで、「実行を制御する」レイヤーではない、と分けて考えるのが正解だと思います。
アノテーションは「モデルに文脈を与える」レイヤーで、「実行を制御する」レイヤーではない、と分けて考えるのが正解だと思います。
テキトー教師DotAI 認定講師この区別は講座でも必ず伝えているところで、ヒントと強制は別物なんですよ。ここを混同すると「アノテーションを付けたのに削除が実行された」という誤解につながります。
室谷代表取締役なお、このMCPアノテーションはTypeScriptのみの対応です。Python側で同じことをしたい場合の扱いは、現時点では明らかにされていません。
システムプロンプトを自前のものに置き換える方法と注意点
室谷代表取締役4つ目が、システムプロンプトの置き換えです。
Agent.create()のsystemPromptに自前のテキストを渡すと、メインのエージェントループで使われるCursor組み込みのシステムプロンプトが、そのテキストに置き換わります。テキトー教師DotAI 認定講師ここで安心材料なのが、ルール、スキル、ツールスキーマは引き続き読み込まれるという点と、サブエージェントは独自のプロンプトを保つという点です。全部が真っさらになるわけではなくて、メインループのプロンプトだけが差し替わるイメージですね。
室谷代表取締役自社のプロダクトにエージェントを埋め込むとき、振る舞いを自社の言葉で規定したいというのは必ず出てくる要望なんですよ。それがSDKのオプション一つでできるようになったのは大きいです。
テキトー教師DotAI 認定講師ただ注意点もあって、これはTypeScriptのローカルエージェント限定です。しかも
resumeで消えてしまうと「なぜか振る舞いが戻った」という事故になるので、ここは実装時に気をつけたいところです。
Agent.resume()のときにもう一度渡す必要がある、と公式に書かれています。resumeで消えてしまうと「なぜか振る舞いが戻った」という事故になるので、ここは実装時に気をつけたいところです。
室谷代表取締役あともう一つ、アクセスはアカウント単位で有効化されると書かれています。「アカウントごとに有効にしている」という表現なので、いきなり全員が使えるわけではない可能性があります。
自分のアカウントで使えるかどうかは、実際に試すか公式の案内を確認するのが確実です。
自分のアカウントで使えるかどうかは、実際に試すか公式の案内を確認するのが確実です。
テキトー教師DotAI 認定講師この「順次有効化」は見落としやすいポイントなんですよ。ドキュメントに機能が載っているのに手元で動かない、というときは、まずここを疑うといいですね。
Cursor SDKの対応範囲と言語別の違い（TypeScript・Python・クラウド）
室谷代表取締役ここまでで一番混乱しやすいのが対応範囲なので、一度きれいに整理しておきたいんですよね。
テキトー教師DotAI 認定講師そうですね。整理するとこうです。
| 機能 | 対応範囲 |
|---|---|
run.steer() | TypeScriptのローカルランのみ。クラウドランはrevert_to_followupを返す |
| バックグラウンドサブエージェントの結果回収 | ローカルのTypeScriptとPython |
| MCPアノテーション | TypeScriptのみ |
systemPromptによる置き換え | TypeScriptのローカルエージェントのみ。Agent.resume()でも再指定が必要。アカウント単位で有効化 |
室谷代表取締役こう見ると、今回の4機能は全部が全部Pythonで使えるわけではないんですよね。Pythonで組んでいる人は、バックグラウンド結果の回収だけが今回の対象、という理解になります。
テキトー教師DotAI 認定講師あと、SDK全体の前提として、TypeScript版はNode.js 22.13以降が必要で、
インストールは
@cursor/sdkというパッケージ名でnpmからインストールします。Python版はcursor-sdkで、Python 3.10以降が必要です。インストールは
npm install @cursor/sdkとpip install cursor-sdkになります。室谷代表取締役認証は
CURSOR_API_KEYを設定するか、apiKeyを渡す形です。ユーザーAPIキーとサービスアカウントAPIキーの両方が使えますが、Team Admin APIキーはまだサポートされていない、と公式に書かれています。テキトー教師DotAI 認定講師ランタイムは
Agent.create()にlocalを渡すかcloudを渡すかで決まります。ここで言う「ローカル」はエージェントループとファイルアクセスが手元で動くという意味で、モデルの推論自体はどちらのモードでもCursorのホスト型モデルを通る、という点は誤解しやすいので押さえておきたいですね。室谷代表取締役料金や利用条件は、SDKのランもIDEやCloud Agentsからのランと同じ料金、リクエストプール、プライバシーモードのルールに従う、と説明されています。利用状況はチームのダッシュボードでSDKタグ付きで表示されるようです。
テキトー教師DotAI 認定講師具体的な金額やレート制限の数値は、今回の資料では明らかにされていません。ここは公式の料金ページを確認するのが確実です。
室谷代表取締役それと、クイックスタートではローカルのエージェントがツール呼び出しを自動承認する、つまりヘッドレスでは人間の承認プロンプトが出ない点も書かれています。ツール呼び出しを制御したいならフックを設定するか、サンドボックスを有効にする必要がある。
ここはCIに組み込む前に必ず確認したいところです。
ここはCIに組み込む前に必ず確認したいところです。
テキトー教師DotAI 認定講師エージェントをCIやバックエンドに組み込む流れは、Codex入門：OpenAIのAIコーディングエージェントを徹底解説で扱っているような自動化の延長線上にあるので、そちらも参考にしながら設計すると整理しやすいですよ。
室谷代表取締役あと、SDKの使い方としては、Cursorの中で
/sdkスキルを実行すると始められる、と案内されています。公式のCookbookにはSDKクイックスタートやアプリビルダーのプロトタイピングツール、クラウドエージェント用のカンバンボード、コーディングエージェントCLIといったエンドツーエンドの例があるので、CIの自動修正ボットやバグトリアージ、コードレビューの自動化あたりから入るのが現実的だと思います。よくある質問
室谷代表取締役ここからは、実際に触る前に気になる点をまとめておきます。
テキトー教師DotAI 認定講師まず「Cursor SDKで何ができるのか」ですが、Cursor IDEやCLI、Webで動くのと同じエージェントを、自分のコードから呼び出して動かせます。ローカルとクラウドのランタイムを同じインターフェースで扱えるので、呼び出し側のコードは実行場所を変えても同じものを書けます。
室谷代表取締役「TypeScriptとPythonで導入方法は違うのか」については、TypeScriptが
npm install @cursor/sdkでNode.js 22.13以降、Pythonがpip install cursor-sdkでPython 3.10以降です。パッケージ名が違うので、そこだけ注意すれば基本の考え方は共通です。テキトー教師DotAI 認定講師「APIの基本的な使い方」は、
Agent.create()でエージェントを作り、agent.send()でプロンプトを投入してランを開始し、run.stream()でイベントを流し込みながら受け取るか、run.wait()で完了を待って結果を取る、という流れです。エージェントは会話状態を保持する永続的な入れ物で、ランは1回のプロンプト投入、という関係になります。室谷代表取締役「CI/CDやバックエンドへの組み込み」は、ローカルランなら開発スクリプトやCIチェック、クラウドランならリポジトリを持っていない呼び出し元や並列実行、呼び出し元が切断されても走り続けてほしい場合、というのが公式の使い分けです。
テキトー教師DotAI 認定講師「料金や制限」については、SDKのランはIDEやCloud Agentsと同じ料金、リクエストプール、プライバシーモードのルールに従う、とされています。具体的な金額やレート制限の数値は今回の資料では明らかにされていません。
室谷代表取締役「Cursor IDEのエージェントとの違い」は、同じエージェントをコードから呼べるようにしたものがSDK、という関係です。SDKから開始したクラウドエージェントはデフォルトのエージェント一覧からは除外されていて、Cursor WebやCursorのウィンドウで見るときはFilterからSourceのSDKを選ぶ、という仕様になっています。
テキトー教師DotAI 認定講師最後に「実際のユースケース」ですが、公式が挙げているのはCIの自動修正ボット、バグトリアージのワーカー、コードレビューのパス、プロダクトに埋め込むエージェント、オーケストレーターあたりです。今回の
steer()やバックグラウンド結果の回収は、まさにこういう長時間・並列のユースケースを想定した機能だと言えます。室谷代表取締役というわけで、今回の1.0.31は「エージェントを本番のワークフローに置けるか」という問いに対して、かなり実務的な答えを出してきたアップデートだと思います。対応範囲が機能ごとに違うので、そこだけ丁寧に確認しながら試してみてください。
