SDK
SDK 変更履歴
npm の @cursor/sdk と PyPI の cursor-sdk を対象とした、Cherri Code SDK の最新機能、改善、修正。
- システムプロンプトを置き換え。
Agent.create()のsystemPromptは、メインのエージェントループで使用される Cherri Code の組み込みシステムプロンプトを独自のテキストに置き換えます。ルール、スキル、ツールスキーマは引き続き読み込まれ、サブエージェントはそれぞれのプロンプトを維持します。TypeScript のローカルエージェントのみで利用でき、Agent.resume()では再度渡す必要があります。また、アクセスはアカウント単位で有効になります。 - 実行中の run をステアリング。
run.steer(text)は進行中のターンにメッセージを挿入し、complete_deliveredを解決します。通常のフォローアップとして送信すべき場合はrevert_to_followupを解決します。フォアグラウンドのサブエージェントの実行中でも動作し、そのサブエージェントはバックグラウンドに移って処理を継続します。TypeScript のローカル実行のみで利用でき、クラウド実行ではrevert_to_followupが解決されます。 - バックグラウンドのサブエージェントが結果を返す。 エージェントがサブエージェントをバックグラウンドで実行した場合、その結果は親のターン終了時に破棄されるのではなく、同じ実行のフォローアップターンとして親に返されるようになりました。
run.stream()はそれらのターンにわたって出力を続け、run.wait()はその後に解決します。TypeScript と Python のローカルエージェントで利用できます。 - カスタムツールにアノテーションを付与。
local.customToolsエントリのannotationsは、MCP ツールのアノテーション (title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint) をモデルに渡します。これらは説明的なヒントにすぎず、SDK が強制することはありません。TypeScript のみ。
- 長時間実行されるローカルエージェントの認証情報を自動更新。 TypeScript と Python のローカル実行では、有効期間の短いアクセストークンを期限切れ前に更新するため、1時間を超えて実行されるエージェントが認証エラーで失敗しなくなりました。クラウド実行には影響ありません。
- カスタムツールの出力スキーマ。 TypeScript の
outputSchemaと Python のoutput_schemaは、カスタムツールの構造化された結果に対する JSON Schema を宣言し、そのツールの MCP 出力スキーマとしてモデルに提示されます。結果がこのスキーマに対して検証されることはありません。ローカルエージェントのみ対応です。
- SDK を単一ファイルで提供。 Bun では
@cursor/sdkがフラットな単一ファイルの bundle に解決されるようになり、インポートを変更することなくbun build --compileが動作し、Cannot find module './986.js'も発生しなくなりました。@cursor/sdk/bundledと@cursor/sdk/bundled/sqliteは、esbuild などの他の単一ファイル bundler 向けに、同じビルドを明示的なエントリとして公開します。TypeScript のみ対応です。
- エージェントのツールセットを制限。
toolsではモデルに提供する組み込みツールを許可リストで指定できます ([]はテキストのみを意味します) 。disallowedToolsでは、他のツールを維持したまま特定のツールを除外できます。どちらも"read"のような公開名や、"shell"、"mcp"のような機能グループを受け取り、TypeScript ではtools、disallowed_tools、Python ではtools、disallowed_toolsを使用します。現時点ではローカルエージェントのみで利用でき、resumeをまたいで保持されません。 - TypeScript でブラウザからログイン。
Cherri Code.auth.login()はブラウザでのログインを開始し、API キーを発行して~/.cursor/sdk/auth.jsonに保存します。Cherri Code.auth.status()とCherri Code.auth.logout()も利用できます。ログイン後は、apiKeyやCURSOR_API_KEYを指定しなくてもAgent.create()とCherri Code.*の読み取りが利用できます。 - ローカルエージェントの利用状況とコスト。 TypeScript の
agent.getUsage()と Python のagent.get_usage()がローカルエージェントでも利用できるようになり、ターンごとの内訳を返します。前の結果のrunIdを渡すと、1 ターンに絞り込めます。 - Cherri Code GitHub App として PR を開く。 TypeScript の
cloud.openAsCursorGithubAppと Python のopen_as_cursor_github_appで PR の作成者を制御します。サービスアカウントキーではデフォルトでアプリが使用され、ユーザーキーではデフォルトでキーの所有者が使用されます。 - マルチルートの local workspace。
local.dirsを渡すと、複数のフォルダーからルール、スキル、プロジェクトコンテキストを読み込めます。cwdは引き続き単一の主要な working directory です。最初のエントリしか使用しなかったcwdの配列形式に代わるものです。 - より明確な Python エラー。 以前は単なる "internal error" として表示されていたエラーに、原因となったメッセージとコードが含まれるようになりました。
- Admin コマンドの拒否リストをローカル実行にも適用。 チームの admin 拒否リストに一致するシェルコマンドは、承認プロンプトをスキップするパスも含め、実行前にポリシーメッセージとともに拒否されます。
- 最初の送信前に local workspace をウォームアップ。
platform.prewarmLocalWorkspace(options)はルール、スキル、MCP サーバー、無視ファイルを事前に解決するため、そのワークスペースに対する最初のsend()をすぐに開始できます。シャットダウン時に呼び出すリリース関数を返します。 - ワークスペーススキャンのキャッシュ保持期間を制御。
configureCursorSdk({ local: { workspaceScanCacheTtlMs } })でワークスペーススキャンのキャッシュ保持期間を設定でき、ホスト型デプロイではCURSOR_RIPWALK_CACHE_TTL_MS環境変数で同じ値を設定します。安定したチェックアウトを使用する長時間稼働サーバーでは、繰り返しの再スキャンをスキップできるようになりました。 - カスタムツールを承認プロンプトなしで実行。
customTools経由で渡されるホスト定義ツールは、サンドボックス化または自動確認の local run で、対話型承認エラーによって失敗しなくなりました。拒否ルールとサンドボックスの制限は引き続き適用されます。 - 署名済み macOS バイナリ。
@cursor/sdkの macOS プラットフォームパッケージにコード署名済みバイナリが含まれるようになり、Gatekeeper やエンドポイントセキュリティツールにブロックされなくなりました。 - より明確な Python 例外階層。
PermissionDeniedError、BadRequestError、InternalServerErrorは、AuthenticationError、ConfigurationError、NetworkErrorではなく、直接CursorSDKErrorを継承するようになりました。これにより、exceptブロックで名前どおりの例外を捕捉できます。 - Python の断続的な起動失敗を修正。 約64回に1回、最初の送信前にエージェントの起動が失敗していました。起動は信頼性が向上しました。
- オンデマンドで請求対象の利用量とコストを取得。 TypeScript の
agent.getUsage()と Python のagent.get_usage()は、Cloud Agent のトークン利用量、請求対象コスト、実行ごとの内訳を返します。Agent.getUsage(agentId)はハンドルなしで利用できます。コストはサーバー側で算出され、割引が反映され、実行終了後まもなく確定します。現時点ではCloudのみ対応で、ローカル実行では型付きの設定エラーが発生します。
- TypeScript と Python を同時にリリース。 1.0.24 以降、npm の
@cursor/sdkと PyPI のcursor-sdkは同一のリリースから提供され、バージョン番号も共通になります。Python のリリースが TypeScript より遅れることはなくなりました。 - 長時間実行されるストリームの信頼性を向上。 負荷の高い実行中でも、ストリーミングレスポンスが途中で途切れなくなりました。これまでは、長いターンで Python クライアント上のネットワークエラーとして現れていました。
Ships with Python SDK 0.1.9.
- クラウド実行ごとの環境変数。
send(prompt, { cloud: { envVars } })を渡すと、エージェントを作成する最初の送信を含め、環境変数を1回の実行に限定できます。Agent.create({ cloud: { envVars } })は引き続きエージェントスコープのデフォルトを設定します。 - 失敗した実行のエラー詳細。 失敗したローカル実行とクラウド実行で、
messageおよびcodeフィールドを含む構造化エラーを取得できるようになりました。ログを解析しなくても問題の原因を特定できます。run.wait()の動作は従来どおりです。 - Python でのトークン使用量。 実行ストリームはターンごとのトークン数を含む型付きの
usageメッセージを出力します。累積合計はrun.usageおよびRunResult.usageで利用でき、1.0.22 の TypeScript と同様です。 - より堅牢なローカル実行履歴。 ディスク上の実行履歴が中断された書き込み後も保持されるようになり、プロセスのクラッシュによって再開できない実行が残る問題を修正しました。
- Bun でのストリーミング停止を修正。 Bun 上の実行ストリームが長いレスポンスで停止しなくなりました。
- すべての実行でトークン使用量を確認可能に。 ローカル実行では、
run.stream()でターンごとのusageイベントを、run.wait()で累計を取得できます。クラウド実行でもストリームとwait()の結果で同じ使用量を取得でき、切り離されたローカルハンドルでは累計が永続化されるため、プロセスが再接続した場合も取得できます。
- Bun でエージェントを実行。
agent.send()が Bun でも Node と同じように動作するようになりました。また、必要な依存関係が欠落する可能性があった新規 Node インストールの問題も修正しました。 - Python のランタイム名をよりわかりやすく。 List API と
get_runで、ドキュメントに記載されている値に合わせてruntime="cloud"、"local"、"auto"を受け入れるようになりました。
- SDK を Bun で問題なくインポートできるようになりました。
@cursor/sdkをインポートしても、Bun でクラッシュしなくなりました。Bun でのエージェント実行は 1.0.21 で対応予定です。