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, so 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

Node.js 22.13 is a specific enough floor that I would check it first when an install works on a laptop and fails on a build runner. The import behaviour is quieter. Importing @cursor/sdk does not eagerly load the local agent stack, because the local executor only loads on the first local acquire, so cloud-only and type-only consumers never pay that cost. The first local agent in a process pays it once and the module stays cached after that, which is worth remembering if you ever time one run and treat it as typical.

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.

The cloud trigger about runs surviving a disconnected caller is the one that tends to surface late, after something has already been built on local. Local is less fragile than that makes it sound: local handles can detach and reattach, and since 1.0.23 run history on disk survives interrupted writes. What local does not give you is a machine that keeps working when yours stops. The loop is inline in your Node process, so a runner that reclaims the job takes the run with it.

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.

Because the agent is the durable half, the move is to create one and keep it. Build a fresh agent per prompt and you throw away the conversation state, which is probably fine for a one-shot script and tiresome for anything that asks follow-up questions, since you end up restating context in every message. There is a caveat running the other way. Agent.create() validates options and returns a handle immediately, so a create that succeeds tells you your options parsed, not that a run will work.

Cursor's own quick start puts that shape on screen: one local agent pointed at the current working directory, then a loop over the events it streams back.

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())

Which shape you copy depends on whether anything downstream has to react before the run finishes. Streaming gives you that; .text() waits and hands back the finished 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 unsupported row is the one that reshapes a plan. Team Admin API keys are not accepted yet, so the team-level credential an admin already holds is not the one your automation can present. The key Cursor documents for team-owned automation is a service account, which is an Enterprise-plan feature: a non-human account an admin creates under Dashboard → Settings → Service Accounts, consuming no extra seat and drawing usage from the team's pool. Its key is shown once at creation and rotated from that same screen.

Teams below Enterprise are left with a user key, so the automation belongs to a person and bills their plan. That is workable at small scale. I would still write down whose key each job runs on, because Cursor's own argument for service accounts is that automations keep running as people and roles change, which is the part a personal key does not cover.

Use the Cursor CLICursor's command line: the full agent, all modes and models, in the terminal and pipeable into scripts and CI. Press Enter for the full definition. when the caller is a shell, and the SDK when the caller is a program that has to do something while a run is still going. agent -p "..." is one prompt in, one result out, which is the right shape for a step in a CI job or a git hook. The SDK hands you objects instead: an agent that survives across prompts, and a run that owns its own stream, status, result and cancellation.

Streaming on its own is not the dividing line, granted, since the CLI can emit streamed JSON as well. The difference is that SDK events arrive as normalized SDKMessage values inside your process, against a handle you already hold, rather than a subprocess you parse and signal. If neither shape fits, Cursor points callers who want REST at the Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. API instead.

Use the SDK Bridge, which Cursor describes as a small local server that embeds the TypeScript SDK and exposes the same agent surface over a stable Connect/protobuf protocol. The docs are careful about what it is for: if you write TypeScript or Python, install the first-party SDK instead, and Python already talks to a bundled copy of the bridge. The bridge exists so a platform team can write a thin adapter in Go, Rust, Java, C# or anything else, and Cursor's framing is that it is for SDK authors and platform teams, while application code should still depend on @cursor/sdk or cursor-sdk.

The mechanics are plain once you see the shape. Your adapter spawns cursor-sdk-bridge, or attaches to one your platform already runs; the bridge binds a loopback HTTP/1.1 port and serves the sdk.v1 services. Classic gRPC over HTTP/2 will not connect, so you use a Connect client or plain POSTs with protobuf or JSON bodies. Two secrets are involved, and the docs keep them separate: your Cursor API key (user or service account keys; Team Admin keys are not supported yet) goes on create, resume and catalog calls and in the bridge's environment, while a per-process bearer token, generated during the ready-line handshake, goes on every RPC including streams. The bridge listens on 127.0.0.1 by default.

What I would take from the docs is the support boundary rather than the protocol. Cursor publishes and supports the sdk.v1 contract and the bridge binaries; it says adapters in other languages are not first-party SDKs, and to lead with TypeScript or Python unless you need a language they do not cover. Because the bridge embeds @cursor/sdk, new agent features land once in the bridge and adapters pick them up by bumping the binary, which is the reason to pin a release and vendor proto/ untouched. The docs even hand you a starting prompt: point a Cursor agent at the repo and have it build the adapter, covering codegen from proto/sdk/v1, process lifecycle, streaming, errors and callback servers.

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 rather than all at once: importing stopped crashing in 1.0.20, agent.send() started working in 1.0.21, and streams stopped stalling on long responses in 1.0.23. 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.

Cursor says the release it calls current, 1.0.23, publishes self-contained .d.ts files, so types resolve without pulling in unpublished workspace packages, and stream types such as TurnEndedUpdate come back as real types instead of any. The docs also tell you to re-run your typecheck after upgrading, which is an easy line to skip. Code written while those events were untyped compiled because nothing was checking it, and it may not compile once they are.