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

We've shipped a batch of new functionality across the TypeScript and Python SDKs. You can now choose how agent and run metadata is persisted, expose your own functions to the agent as tools, route local tool calls through auto-review, and nest subagents to any depth. This release also brings a set of reliability, performance, and platform fixes that make local and cloud SDK agents easier to run in production scripts, CI, and custom integrations.

Custom tools

You can now hand the local agent your own tools by passing function definitions through local.customTools, on Agent.create() or per send(). The SDK exposes them to the agent through a built-in MCP server called custom-user-tools, so the model calls your code through the same path and the same permission gate as any other MCP tool.

Before this, exposing a custom capability meant standing up your own stdio or remote HTTP MCP server and wiring it into the agent. Now a function definition is enough. Custom tools are also visible to every subagent of a parent agent, so a tool you define once is available throughout the whole run.

Auto-review

By default, a local SDK agent runs tool calls without asking for approval, since there's no human in the loop in a headless run. Set local.autoReview to route those calls through auto-review instead. A classifier decides which calls run automatically and which to hold back, rather than bypassing review entirely.

You steer that classifier with natural-language instructions in permissions.json. The autoRun.allow_instructions field describes call shapes to lean toward allowing, and autoRun.block_instructions describes the ones to hold for review. For example, you can allow read-only inspections of build artifacts while always pausing on destructive operations like deletes.

`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 and custom stores

Both SDKs persist agent and run metadata so you can resume an agent after a process restart. Until now, that store was SQLite. You can now opt into a JSONL store instead, which writes a plain, append-only file you can read, diff, and check into version control. Both SqliteLocalAgentStore and JsonlLocalAgentStore are exported directly.

If neither default fits your setup, implement the public LocalAgentStore interface and pass it through local.store. Build an in-memory store for ephemeral CI runs, or back persistence with Postgres when you want agent state to live next to the rest of your application data. The Python SDK exposes host, JSONL, and composed JSONL stores through the bridge.

Nested subagents

Subagents can now spawn their own subagents, and so on. A reviewer subagent can delegate to a test-writer, which can delegate further, with each level keeping its own prompt and model. There's nothing to turn on; a subagent session registers the executor it needs to call Task, so nesting works automatically for any agent that defines subagents.

Reliability, performance, and platform improvements

This release also includes a batch of quality-of-life fixes across both SDKs.

Reliability

Run correlation: Every send() now carries a platform-generated requestId, exposed on Run and RunResult and persisted across the in-memory, SQLite, and JSONL stores. Tie a script or CI run to backend logs, analytics, and support threads without inferring it from agentId.

Reliable wait() on local runs: Local runs no longer resolve wait() before the terminal result is written. Hydration keeps refreshing until the run reaches a final state, so automation reads a complete result.

Safe checkpoints on dispose: Disposing a local agent no longer removes checkpoint data when a root reference is missing but checkpoint blobs still exist. The agent directory is only cleared when there's genuinely nothing left to keep.

Cloud streaming over HTTP/1.1: Cloud agent sessions now stream correctly on HTTP/1.1 transports used by some proxies, older Node fetch stacks, and certain CI images. HTTP/2 behavior is unchanged.

Performance and packaging

Lighter import: Importing @cursor/sdk no longer eagerly loads the full local agent stack. Cloud-only and type-only consumers skip the local runtime cost until the first local call, with no API change. The first local call pays a one-time import, then stays cached.

Self-contained TypeScript types: Published .d.ts files no longer reference unpublished workspace packages. This fixes TS2305 and TS2307 errors under skipLibCheck: false and silent any on stream types like TurnEndedUpdate.

Bundled ripgrep: Local shell runs use the bundled platform rg binary without modifying your global PATH. On Windows, prepending ripgrep no longer clobbers the Path variable.

Models

Composer 2 routes to Composer 2.5: SDK clients still pinning retired composer-2 slugs are routed to Composer 2.5 automatically, keeping fast variants intact, so older scripts keep running.

Python SDK

Workspace-scoped list_runs: Client, AsyncClient, and Agent.list_runs take an optional cwd, and the bridge falls back to its launch workspace. This fixes spurious "agent not found" results when the bridge runs as a subprocess.

Clearer not-found errors: Looking up an agent that isn't in the resolved workspace returns a clear not-found error instead of an opaque internal error.

0.1.6 release and analytics: cursor-sdk 0.1.6 documents the Buildkite release path and labels SDK usage as sdk-python- for clearer analytics.

Run npm install @cursor/sdk or pip install cursor-sdk to upgrade. Scripts pinning composer-2 move to Composer 2.5 automatically, and requestId is a safe addition to your run metadata schema. See the TypeScript and Python docs for full details.