Cursor SDK Agents Guide

Most of the update controls what an SDK agent can reach and how you inspect a run afterwards: custom tools, auto-review, durable stores and request IDs. The table gives the option and API names for each.

Cursor's release notes and announcements say what changed. They don't say how a team should act on it. The steps below are our suggested order, and the next section lists what to watch out for along the way.

1. 1Define one SDK agent job with explicit input, output and owner.
2. 2Expose only the product functions the job needs as custom tools.
3. 3Choose SQLite, JSONL or a custom store based on your audit and retention needs.
4. 4Use auto-review and request IDs so headless runs stay inspectable.

Each item below is either a fact about the release, such as its beta status or plan access, or our advice for using it safely. Plan around each one, and recheck the facts when Cursor ships an update.

• Validate custom-tool inputs as if the model were an untrusted caller, because the model decides what arguments each tool receives.
• Don't store secrets or full transcripts when a summary is enough.
• Use auto-review as a gate, not as proof that a human review is unnecessary.

Agents that don't write code

The SDK is an agent you program, so it can run jobs that never touch code, in finance, legal, support, design or security. One example is a security-questionnaire app. You upload the questionnaire, and it starts a cloud agent that does a first pass using the company's security docs, privacy policies and trust-center content.

Chaining agents and custom UIs

Use the language of the system that calls the agent. Cursor documents Python and TypeScript SDKs against the same agent runtime, so the bigger decision is where the runtime goes: local files, Cursor-hosted cloud or a self-hosted cloud pool.

Decide before you write the agent, because the key decides whose budget each run spends. User API keys and service-account keys both work for local and cloud runs. A user key bills to that person's plan. A service-account key, created in team settings on the Enterprise plan, bills to the team that owns it. Team Admin API keys are not supported yet.

So treat the key as a budget decision. Reuse whichever key was nearest, and a nightly job can spend one engineer's allowance for a month. Nobody notices until that engineer runs out in the middle of an afternoon.

SDK spend shows up under the SDK tag in the team usage dashboard. It follows the same pricing, request pools and Privacy ModeCursor's setting that guarantees code data is not used for training by Cursor or its model providers, and that an admin can enforce org-wide; data-retention terms are a separate, contractual layer. Press Enter for the full definition. rules as a run started from the editor, so a script that iterates over a hundred files competes with your developers for the same pool. Set the spend limit before that script runs. Neither key needs a new seat: a user key runs on its owner's plan, and a service account doesn't consume a seat license. So nobody has to ask for a license before a script starts spending.

No. In Cursor's SDK docs, local describes where the agent loop and filesystem access run, not where the model runs. All inference goes through Cursor's hosted models in both local and cloud modes. The docs give the point its own heading: "Local means local agent loop, not local model."

This matters most to the people least likely to read the SDK docs. If a security reviewer has written down that no code leaves your infrastructure for inference, the local runtime does not meet that rule. Picking local because the name sounded right is a mistake that tends to surface late in a review instead of early in the design.

The self-hosted cloud option decides where code, secrets and build artifacts live. Inference still calls out to external model providers there, just as the desktop app calls a provider API. So a private worker gives you a guarantee about storage and adds nothing about inference.

The runtime choice gets easier once you stop treating it as a privacy control. Local suits a caller that already has the working tree. Pick cloud when the caller shouldn't keep the repo, or when runs must survive a disconnect. The SDK reference covers the rest of the mechanics.

Pin the version that shipped the capability you rely on.

Start with the package names. The npm package is @cursor/sdk, with the leading @, and it requires Node.js 22.13 or later. The bare cursor/sdk does not exist. The Python package on PyPI needs Python 3.10 or later.

Per-run token counts are the clearest case. They have existed since 1.0.22 in TypeScript and 1.0.23 in Python, so any cost-attribution script you write has that as its floor. Bun support arrived in stages too: a clean import in 1.0.20, running agents in 1.0.21, and no stalled streams in 1.0.23.

Since 1.0.24, the npm and PyPI packages ship from the same release and share a version number, so Python no longer trails TypeScript. Check the registry for the current version instead of copying one from a docs page. Then pin it exactly, because a note that Bun works doesn't tell you which release made it work.

When a schedule or an event that Cursor already triggers on can start the job. An automation then covers it with no code for you to own. Automation triggers include cron, a GitHub event, a Slack message, a Linear issue, a PagerDuty incident and a webhook carrying any payload you like. The webhook trigger alone covers many jobs that would otherwise need an SDK script.

The SDK earns its place when the caller is your own software. You want a run's events inside your own interface, its state in your own store, or an agent that something in your product starts. That is where we draw the line, and the line moves as Cursor adds triggers.