Cursor SDK Lands in Public Beta: Programmatic Agents in TypeScript with Local and Cloud Runtimes

Cursor announced the Cursor SDK on April 29, 2026, shipping a TypeScript package that exposes the same agent runtime, harness, and models that power the Cursor desktop app, CLI, and web app. The SDK is in public beta for all users on day one, installable as @cursor/sdk, and billed on standard token-based consumption pricing. It is the largest move yet to turn Cursor from an editor product into a programmable platform.

For where the SDK sits in the broader Cursor surface, see our Cursor 3.2 launch coverage and the Cursor canvases piece.

Key Takeaways

• Launch date: April 29, 2026, public beta, available to all users.
• Package: npm install @cursor/sdk. Authenticate with CURSOR_API_KEY (user or service-account keys).
• Three runtimes: local (inline in your Node process), Cursor-hosted cloud (dedicated VMs with the repo cloned in), and self-hosted cloud (same shape, your pool).
• Core API: Agent (durable container), Run (a single prompt + stream), SDKMessage (normalized event union). Methods: Agent.create, Agent.resume, agent.send, run.stream, run.wait, run.cancel.
• Batteries included: codebase indexing and semantic search, MCP server support, .cursor/skills/ custom skills, hooks, and subagent delegation -- the same primitives that ship inside Cursor.
• Models: all Cursor-supported models, including Composer 2, which the docs describe as offering "frontier-level performance at a fraction of the cost."
• Pricing: "Available to all users and is billed based on standard, token-based consumption pricing."

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.

A minimal example from the SDK docs:

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

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  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 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 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 you can run on your own pool.

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:

• Codebase indexing and semantic search. Agents can retrieve relevant files via the same indexing that powers Cursor's in-editor @codebase queries.
• MCP server integration. Agents can call MCP tools from servers you wire in. Note the beta caveat: inline MCP servers are not persisted across Agent.resume(), so you re-pass them when you reattach.
• Custom skills from .cursor/skills/. The same on-demand skills format the editor uses. Drop a skill into the directory and the SDK agent can load it.
• Hooks. File-based via .cursor/hooks.json for now -- no programmatic callback registration yet, which the docs flag as a beta limitation.
• Subagent delegation. Agents can spawn subagents, the same primitive Cursor 3.2's /multitask command uses inside the editor.

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). 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 tool call schemas are unstable in beta, so parse args and result defensively.
• Account utilities -- Cursor.me() for the authenticated identity, Cursor.models.list() for available model ids.

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 with codebase indexing on, 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 indexing is the unlock; without it you would be re-implementing semantic 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.

Public-Beta Caveats Worth Planning Around

The docs are unusually candid about beta limitations. The ones that affect real integrations:

• APIs may change before GA. Pin the SDK version and budget time for migration before depending on it for production.
• 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 yet implemented for local agents. Plan around this if you need agents to produce downloadable bundles from the local runtime.
• Tool call schemas are unstable. Treat args and result as unknown and validate at the boundary; do not assume a stable shape.
• Hooks are file-based only. .cursor/hooks.json is the only path. There is no programmatic registration in the beta.
• 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 the SDK is at "build internal tools and prototypes" maturity, not "ship as the only path to your production system" maturity.

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. Expect more cloud-side features (durable artifacts, scheduled runs, persistent triggers) to land here next.
• 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 Cursor SDK announcement and the TypeScript SDK reference are the canonical references. Pair them with the SDK release changelog entry for what shipped on day one. For where this fits in the broader Cursor product arc, our Cursor 3.2 coverage is the right starting point.