The Cursor SDK: Run the Agent From Your Own Code

The Cursor SDK is the programmatic way to run the same agent you use in the editor. Cursor's framing is that the SDK wraps local and cloud runtimes behind one interface, so you write the same code regardless of where the agent runs. It ships in two languages, and since release 1.0.24 they ship together from the same release and share a version number — Python no longer trails TypeScript.

One installation detail catches people out often enough that Cursor documents it explicitly: the npm package name starts with an @, and the bare cursor/sdk does not exist on npm. The TypeScript package is also Node-first by design — it ships per-platform @cursor/sdk-<os>-<arch> binaries for sandboxing and ripgrep.

npm install @cursor/sdk

pip install cursor-sdk

Both runtimes expose the same interface, and you choose between them by which key you pass to Agent.create() — local or cloud — using the same CURSOR_API_KEY either way. What changes is where the agent loop runs and where your files live.

There are three objects to learn, and the split between the first two is what makes multi-turn work straightforward: the agent holds the conversation, and each prompt gets its own handle for streaming and cancellation.

In practice that means creating an agent once, then sending prompts against it and iterating the event stream. Cursor's own quick start is a local agent pointed at the current working directory:

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2.5" },
  local: { cwd: process.cwd() },
});

const run = await agent.send("Summarize what this repository does");

for await (const event of run.stream()) {
  console.log(event);
}

The Python equivalent uses a context manager and returns the text directly, which is the shorter path when you do not need to stream events:

import os

from cursor_sdk import Agent, LocalAgentOptions

with Agent.create(
    model="composer-2.5",
    api_key="crsr_key",
    local=LocalAgentOptions(cwd=os.getcwd()),
) as agent:
    print(agent.send("Summarize what this repository does").text())

Authentication is a single environment variable, CURSOR_API_KEY, or an apiKey option passed directly. The part worth checking before you plan a rollout is which kind of key is accepted, because one common choice is not supported yet.

The SDK moves quickly and the changelog is versioned, so it is worth knowing which release introduced the capability you are relying on rather than assuming it is present. The entries below are Cursor's own, newest first.

Two things follow from that list. Bun support arrived in stages — clean import in 1.0.20, running agents in 1.0.21, no stalled streams in 1.0.23 — so pin a version rather than trusting a general claim that Bun works. And per-run token counts have only existed since 1.0.22 in TypeScript and 1.0.23 in Python, which is the floor for any cost-attribution script you write against the SDK.