Cursor SDK Agents Guide

Cursor's June 2026 SDK update added TypeScript and Python support for custom tools, local auto-review, JSONL and custom stores, nested subagents, request IDs and reliability fixes for local and cloud agent apps.

Knowing what shipped is the easy part. Turning Cursor SDK agents into something a team relies on takes a few deliberate steps, mapped below.

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 audit and retention needs.
4. 4Use auto-review and request IDs so headless runs stay inspectable.

New capability comes with new ways to get it wrong. Keep these boundaries in place as you adopt it.

It is not just for coding

Because the SDK is just an agent you program, teams build non-coding agents on it across finance, legal, support, design and security. A concrete example: a security-questionnaire app where you upload the questionnaire and it spawns a cloud agent that does a first pass using the company's security docs, privacy policies and trust-center content - getting pretty far and saving a lot of time.

Chaining agents and custom UIs

Use the language that fits the system calling the agent. Cursor documents both Python and TypeScript SDKs against the same agent runtime, so the bigger decision is runtime placement: local files, Cursor-hosted cloud or a self-hosted cloud pool.

Decide that before you write the agent, because the key decides whose budget the run lands on. 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, bills to the team that owns it. Team Admin API keys are not supported yet.

So the question is not really about authentication. Reuse whichever key was nearest and a nightly job quietly spends against one engineer's allowance for a month, which nobody notices until that engineer runs out of room mid-afternoon.

SDK spend does show up, and it shows up under the SDK tag in the team usage dashboard. Worth knowing that it draws on 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. A script that iterates over a hundred files is competing with your own developers for the same pool.

Which is the argument for setting the spend limit first. The keys do not consume a paid seat, so the usual gate of asking someone for a licence never happens here.

No. Cursor is explicit about this because the word invites the other reading: 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.

That matters most for 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 satisfy it, and picking local because the name sounded right is the sort of mistake that gets discovered late in a review rather than early in a design.

The self-hosted cloud option is about where code, secrets and build artifacts live. Inference still calls out to external model providers there, exactly as the desktop app calls a provider API, so a private worker is a different guarantee rather than a stronger version of the same one.

The runtime choice is honestly easier once you stop treating it as a privacy control. Local is for a caller that already has the working tree, cloud is for a caller that should not keep the repo or needs runs to survive a disconnect, and the SDK reference has the rest of the mechanics.

Whichever one shipped the capability you are relying on, which is a duller answer than it sounds. The npm package requires Node.js 22.13 or later and its name starts with an @, so @cursor/sdk; 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, no stalled streams in 1.0.23.

There is one wrinkle to know about before you copy a version out of the docs. Cursor's TypeScript page describes the current package as 1.0.23 while the newest changelog entry is 1.0.24, so the prose and the changelog disagree. Check the registry rather than either page.

Pin it. A general claim that some runtime works is not the same as knowing which release made it work.

More often than the enthusiasm suggests. If the job is a schedule or an event Cursor already triggers on, an automation covers it with no code for you to own: cron, a GitHub event, a Slack message, a Linear issue, a PagerDuty incident, or a webhook carrying whatever payload you like. That last one absorbs a lot of what people reach for the SDK to do.

The SDK earns its place when the caller is your own software. You want the 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 I would draw the line. It moves as the trigger list grows, I will admit.

Fewer moving parts is a feature when the thing moving is an agent.