Cursor SDK: Programmatic Cursor Agents in TypeScript and Python, Local or Cloud

The Cursor SDK lets your own code drive the same agent runtime, harness, and models that power the Cursor desktop app, CLI, and web app. Cursor announced it on April 29, 2026 as a TypeScript package in public beta. As of October 9, 2026, it ships for TypeScript (@cursor/sdk) and Python (cursor-sdk), the two release together (1.0.35 is the latest), and Cursor's TypeScript SDK reference no longer labels it beta. Other languages can drive agents through the open-source SDK Bridge. It is the largest move yet to turn Cursor from an editor product into a programmable platform.

For the latest SDK additions, including live steering with run.steer(), see our Cursor SDK 1.0.31 coverage. For where the SDK sits in the broader Cursor surface, see our Cursor 3.2 launch coverage.

Key Takeaways

• Launch date: April 29, 2026, public beta, available to all users. The current docs no longer use the beta label.
• Packages: npm install @cursor/sdk (Node.js 22.13 or later) or pip install cursor-sdk (Python 3.10 or later). Since 1.0.24 both ship from the same release with a shared version number (SDK release notes).
• Auth: CURSOR_API_KEY with a user or service-account key; Team Admin keys are not yet supported.
• Three runtimes: local (agent loop in your process), Cursor-hosted cloud (isolated VM with the repo cloned in), and self-hosted cloud (cloud.env set to a pool or machine you run).
• Core API: Agent (durable container), Run (a single prompt + stream), SDKMessage (normalized event union). Methods include Agent.create, Agent.resume, agent.send, run.stream, run.wait, run.cancel, and, for local runs, run.steer.
• Batteries included: semantic codebase search, MCP server support, skills, hooks, and subagent delegation -- the same primitives that ship inside Cursor.
• Models: any model on your account. The docs' examples use Composer 2.5; Composer 2 is retired and composer-2 requests are rerouted to Composer 2.5 at auth time.
• Pricing: SDK runs "follow the same pricing, request pools, and Privacy Mode rules as runs from the IDE and Cloud Agents," and show up under an SDK tag in the usage dashboard.

What Shipped on Day One

The single sentence framing from Cursor's SDK release changelog: "The agents that run in the Cursor desktop app, CLI, and web app are now accessible with a few lines of TypeScript." That is the whole bet. Cursor is not introducing a separate, lighter-weight agent for SDK use. The SDK exposes the production runtime.

The current quick start from the SDK docs:

import { Agent } from "@cursor/sdk";

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);
}

That snippet is doing several things at once. It instantiates a durable Agent against the current working directory, picks Composer 2.5 as the model, submits a prompt that returns a Run object, and consumes a discriminated-union stream of SDKMessage events. The same call shape works for cloud runtimes -- swap local: { cwd } for cloud: { ... } and the rest of the code does not change. The launch-day version of this snippet used composer-2; it still runs, because Cursor reroutes Composer 2 requests to Composer 2.5.

The Three Runtimes

Runtime selection is the most important architectural decision the SDK forces on you, and it maps cleanly to three real use cases:

The local runtime keeps the agent inline in your Node process, which is the right shape for scripts and CI. The Cursor-hosted cloud option moves execution to dedicated VMs with "secure sandboxing, durable state and session management, environment setup, and context management" per Cursor's SDK announcement -- the production posture for anything multi-tenant or long-lived. Self-hosted is the same primitive routed to a worker pool or machine you operate. Either way, "local" describes where the agent loop and files live, not the model: all inference runs on Cursor's hosted models.

The cleanest mental model is that local is the "I want to drive my laptop with code" runtime, Cursor-hosted cloud is "I want production agents without operating infrastructure," and self-hosted is "I want production agents on infrastructure I already operate."

What's in the Box: Indexing, MCP, Skills, Hooks, Subagents

The SDK does not give you a bare model loop. It gives you the same context layer the Cursor editor uses:

• Semantic codebase search. The built-in tool set includes semSearch alongside shell, edit, read, grep, and the rest, so agents can retrieve relevant files the way the editor's agent does.
• MCP server integration. Agents can call MCP tools from servers you wire in. Inline MCP servers are not persisted across Agent.resume(), so re-pass them when you reattach, or use file-based .cursor/mcp.json.
• Skills. The same on-demand skills format the editor uses, loaded from the workspace (.cursor/skills/ or .agents/skills/).
• Hooks. File-based via .cursor/hooks.json only -- no programmatic callback registration, which the docs list as a known limitation.
• Subagent delegation. Agents can spawn subagents, the same primitive Cursor 3.2's /multitask command uses inside the editor. Since 1.0.31, background subagent results return to the parent run on local agents.
• Custom tools. Local agents can register your own functions as tools without standing up a separate MCP server.

Skipping any of these would have made the SDK feel like a downgraded version of in-editor Cursor. Including all of them is what justifies the framing "the agents that run in the Cursor desktop app, CLI, and web app are now accessible with a few lines of TypeScript." The SDK is the editor's runtime, not a sibling of it.

API Surface in One Page

The shape is small enough to learn in one sitting:

• Agent -- a durable container that holds conversation state. Create with Agent.create, list with Agent.list, get by id with Agent.get, reattach to an existing one with Agent.resume. The static Agent.prompt() is a one-shot convenience that creates, runs, and disposes in a single call.
• Run -- represents a single prompt submission with its own stream and lifecycle. Created by agent.send(prompt). Methods: run.stream() (async generator yielding events), run.wait() (resolve on completion without streaming), run.cancel() (abort an in-flight run). Local runs also expose run.steer(text), which injects a message into the turn already running. Inspect with Agent.listRuns().
• SDKMessage -- the normalized stream event type. A discriminated union, so you switch on the kind to handle each event class. The docs warn that the tool call schema is not stable, so parse args and result defensively; the event envelope (type, call_id, name, status) is stable.
• Account utilities -- Cursor.me() for the authenticated identity, Cursor.models.list() for available model ids, Cursor.auth.login() to mint a key through a browser login, and agent.getUsage() for billed usage and cost.

The mental model: an Agent is a long-lived conversation, a Run is one turn within it, and the stream is how you watch the turn unfold. That is the same shape most modern agent SDKs have converged on.

How the Cursor SDK Compares to Claude Agent SDK and OpenAI Agents SDK

All three frontier vendors now ship a programmatic agent SDK. They are not interchangeable, and the differences map directly to where each company's product strength lives.

The honest read: pick Cursor SDK when you want to ship coding agents and you do not want to rebuild semantic codebase search and skills loading. Pick Claude Agent SDK when you want maximum control over the harness and have your own workspace abstraction. Pick OpenAI Agents SDK when you want a manifest-driven, runtime-managed deployment story.

For deeper architectural framing, see our Codex CLI vs Claude Code vs Cursor architecture piece -- the same axes apply at the SDK layer.

What to Build First

Three concrete projects that play to the SDK's strengths:

1. A repo-aware code review bot. Use the local runtime in CI. On every PR, spawn an agent against the checked-out repo, ask it to review the diff in context of the rest of the codebase, and post the result as a PR comment. The SDK's built-in semantic search is the unlock; without it you would be re-implementing retrieval.
2. A scheduled refactor agent on Cursor cloud. Use the Cursor-hosted cloud runtime. Schedule a nightly agent that picks up a tagged tech-debt issue, runs /multitask-style subagent delegation across the affected modules, and opens a PR with the result. This is the "production agents without operating infrastructure" path.
3. An internal docs assistant with custom skills. Drop a skill into .cursor/skills/ that knows how to query your internal API or hit an internal docs site. Wire an agent to that skill via the SDK and expose it as a Slack bot. The skill loader is the same one Cursor uses internally, which means a skill that works in the editor works in the SDK with no rewrite.

Known Limitations Worth Planning Around

The docs keep a candid known-limitations list. As of October 9, 2026, the ones that affect real integrations:

• Pin your version. The SDK still ships often (1.0.35 as of October 9, 2026), so pin it and read the release notes before upgrading.
• Inline MCP servers are not persisted across Agent.resume(). If you reattach to an agent, re-pass the MCP server config.
• Artifact download is not implemented for local agents. Plan around this if you need agents to produce downloadable bundles from the local runtime.
• Tool call schemas are not stable. Treat args and result as unknown and validate at the boundary; tool names can also be renamed or replaced.
• Hooks are file-based only. .cursor/hooks.json is the only path. There is no programmatic registration.
• Several options are local-only. Custom tools, Auto-review, custom stores, toolset restrictions, and systemPrompt work on local agents only.
• Auth excludes Team Admin keys. User API keys (from the Cursor Dashboard) and service account keys both work; Team Admin keys do not yet.

None of these are blockers for the right use cases. They do mean you should build defensively around the stream format and keep a fallback path for anything production-critical.

What This Tells You About Where Cursor Is Heading

Three inferences from how the SDK is shaped:

• Cursor is becoming a platform, not just an editor. Programmatic access to the editor's runtime is the move that lets Cursor compete on infrastructure surfaces -- CI, internal automations, agent-as-a-service products -- and not only on developer experience inside the editor.
• The cloud runtime is a real bet on Cursor as a hosting product. Dedicated VMs, durable state, environment setup, sandboxing -- this is infrastructure Cursor wants to sell, not just dev tooling. Cloud-side features have kept landing since launch: no-repo cloud agents, per-run environment variables, and billed usage per agent are all in the docs now.
• The context layer is the moat. Cursor's headline differentiator over Claude Agent SDK and OpenAI Agents SDK is that codebase indexing, skills, hooks, and subagents come pre-wired. Anyone can wrap a model in an agent loop. Few have a production-grade IDE context layer to expose through one.

The TypeScript SDK reference, the Python SDK reference, and the SDK release notes are the canonical references today. For the newest features, see our SDK 1.0.31 steering coverage; for Rust, Go, and other languages, see the SDK Bridge.

Corrections and Updates

• October 9, 2026: This page described the SDK as a TypeScript-only public beta with a Composer 2 sample; it now ships for TypeScript and Python at version 1.0.35, the docs no longer label it beta, and the sample uses Composer 2.5.

Sources

• Cursor blog, Cursor SDK announcement (April 29, 2026), read 2026-10-09: https://cursor.com/blog/typescript-sdk
• Cursor changelog, SDK release (April 29, 2026), read 2026-10-09: https://cursor.com/changelog/sdk-release
• Cursor docs, "Cursor TypeScript SDK", read 2026-10-09: https://cursor.com/docs/sdk/typescript
• Cursor docs, "Cursor Python SDK", read 2026-10-09: https://cursor.com/docs/sdk/python
• Cursor docs, "Cursor SDK release notes" (1.0.22 to 1.0.35), read 2026-10-09: https://cursor.com/docs/release-notes/sdk
• Cursor docs, "Cloud Agents" (formerly Background Agents), read 2026-10-09: https://cursor.com/docs/cloud-agent