Cursor SDK にカスタムストア、カスタムツール、自動レビュー機能を追加

TypeScript および Python SDK の両方で一連の新しい機能がリリースされました。これにより、エージェントおよび実行メタデータの永続化方法を選択できるようになり、独自の関数をツールとしてエージェントに公開したり、ローカルツールの呼び出しを自動レビュー経由でルーティングしたり、サブエージェントを任意の深さまでネストすることが可能になりました。今回のリリースではまた、ローカルおよびクラウド SDK エージェントがプロダクションスクリプト、CI、カスタム統合環境でより実行しやすくなるよう、信頼性、パフォーマンス、プラットフォームに関する修正も含まれています。

カスタムツール

これからは、Agent.create() または send() 時に local.customTools を介して関数定義を渡すことで、ローカルエージェントに独自のツールを手渡せるようになりました。SDK はこれらのツールを custom-user-tools という組み込み MCP サーバーを通じてエージェントに公開するため、モデルは他のどの MCP ツールと同様のパスと権限ゲートを通じてコードを呼び出します。

以前は、独自機能を公開するには、独自の stdio またはリモート HTTP MCP サーバーを立ててエージェントに接続する必要がありました。しかし今では、関数定義だけで十分です。カスタムツールは親エージェントのすべてのサブエージェントからも参照可能となるため、一度定義したツールは実行全体で利用可能です。

自動レビュー

デフォルトでは、ヘッドレス実行では人間がループに参加しないため、ローカル SDK エージェントは承認を求めずにツールの呼び出しを実行します。local.autoReview を設定することで、これらの呼び出しを自動レビュー経由でルーティングできます。これはレビューを完全にバイパスするのではなく、どの呼び出しを自動的に実行し、どの呼び出しを保留するかを分類器が判断する仕組みです。

permissions.json ファイル内で、自然言語の指示を用いてこの分類器を制御できます。autoRun.allow_instructions フィールドは許可する傾向にある呼び出し形状を記述し、autoRun.block_instructions フィールドはレビュー保留が必要なものを記述します。例えば、ビルド成果物の読み取り専用検査は許可しつつ、削除のような破壊的な操作については常に一時停止させることができます。

`jsonc { "autoRun": { "allow_instructions": [ "Read-only inspections of build artifacts under ./dist are fine." ], "block_instructions": [ "Always pause delete operations so I get a chance to review them." ] } } `

JSONL とカスタムストア

両方の SDK はエージェントおよび実行のメタデータを永続化するため、プロセス再起動後にエージェントを再開できます。これまでこのストアは SQLite でしたが、現在は JSONL ストアを選択できるようになりました。これは、読み取り・差分比較・バージョン管理へのチェックインが可能なプレーンな追加専用ファイルに書き込むものです。SqliteLocalAgentStore と JsonlLocalAgentStore はどちらも直接エクスポートされます。

デフォルトのいずれも環境設定に適合しない場合は、パブリックな LocalAgentStore インターフェースを実装し、それを local.store を通じて渡してください。一時的な CI 実行用のメモリ内ストアを構築するか、エージェントの状態をアプリケーションデータの一部として維持したい場合は、永続化のバックエンドに Postgres を使用します。Python SDK はブリッジを通じてホスト、JSONL、および合成された JSONL ストアを公開しています。

ネストされたサブエージェント

サブエージェントは現在、独自のサブエージェントを生成できるようになりました。レビュー担当のサブエージェントがテスト作成者に委任し、その作成者がさらに別のレベルに委任することも可能で、各レベルは独自のプロンプトとモデルを保持します。有効化するスイッチはありません。サブエージェントセッションは必要な実行体を登録し、Task を呼び出す必要があるため、サブエージェントを定義するあらゆるエージェントでネストが自動的に機能します。

信頼性、パフォーマンス、およびプラットフォームの改善

本リリースでは、両 SDK において一連の利便性向上のための修正も含まれています。

信頼性

実行相関: すべての send() メソッドに、プラットフォーム生成型の requestId が付与されるようになりました。これは Run および RunResult で公開され、メモリ内ストレージ、SQLite、JSONL ストア間で永続化されます。これにより、agentId から推測することなく、スクリプトや CI 実行をバックエンドログ、分析データ、サポートスレッドに紐付けることが可能になります。

ローカル実行における信頼性の高い wait(): ローカル実行において、ターミナル結果が書き込まれる前に wait() が解決されることはなくなりました。ハイドレーションは実行が最終状態に達するまで継続して更新されるため、自動化スクリプトは完全な結果を読み取ることができます。

破棄時の安全なチェックポイント: ルート参照が存在しない場合でもチェックポイントのブローブ（blob）が残っている状態でローカルエージェントを破棄しても、チェックポイントデータが削除されることはなくなりました。エージェントディレクトリがクリアされるのは、本当に保持すべきものが何もない場合のみです。

HTTP/1.1 によるクラウドストリーミング: クラウドエージェントセッションは、一部のプロキシや古い Node fetch スタック、特定の CI イメージで使用されている HTTP/1.1 トランスポート上でも正しくストリーミングされるようになりました。HTTP/2 の動作には変更はありません。

パフォーマンスとパッケージング

軽量なインポート: @cursor/sdk をインポートしても、ローカルエージェントスタック全体が即座に読み込まれることはなくなりました。クラウド専用および型専用の利用者は、最初のローカル呼び出しまでローカルランタイムのコストを回避できます。API 変更はありません。最初のローカル呼び出しで一度だけインコストが発生し、その後はキャッシュされた状態が維持されます。

自己完結型の TypeScript タイプ: 公開された .d.ts ファイルは、未公開のワークスペースパッケージを参照しなくなりました。これにより、skipLibCheck: false の下での TS2305 および TS2307 エラーが修正され、TurnEndedUpdate などのストリームタイプにおける沈黙的な any 型も解消されました。

バンドルされた ripgrep: ローカルシェル実行では、グローバルな PATH を変更することなく、バンドルされたプラットフォーム固有の rg バイナリが使用されます。Windows では、ripgrep の先頭追加により Path 変数が上書きされる問題も解消されました。

モデル

Composer 2 は Composer 2.5 にルーティング: 廃止された composer-2 スラッグを固定している SDK クライアントは自動的に Composer 2.5 にルーティングされ、高速なバリアントは維持されたまま、古いスクリプトも引き続き実行可能です。

Python SDK

ワークスペーススコープの list_runs: Client、AsyncClient、および Agent.list_runs はオプションの cwd を受け取り、ブリッジは起動時のワークスペースにフォールバックします。これにより、ブリッジがサブプロセスとして実行された際に発生する誤った「エージェントが見つからない」という結果が修正されました。

明確な not-found エラー: 解決されたワークスペースに含まれていないエージェントを検索した場合、不明瞭な内部エラーではなく、明確な not-found エラーが返されます。

0.1.6 リリースと分析機能: cursor-sdk 0.1.6 では Buildkite のリリースパスが文書化され、SDK の使用状況がより明確な分析のために sdk-python- というラベルで識別されるようになりました。

アップグレードするには npm install @cursor/sdk または pip install cursor-sdk を実行してください。composer-2 を固定しているスクリプトは自動的に Composer 2.5 に移行され、requestId は実行メタデータスキーマに安全に追加できます。詳細については TypeScript および Python のドキュメントをご覧ください。