Cursor SDK Tutorial: Run Coding Agents With TypeScript

Cursor announced its TypeScript SDK in late April 2026 and released it as a public beta. The package is published as @cursor/sdk and runs from Node environments such as scripts, CI jobs, and backend services.

The main difference from using Cursor in the editor is where the task starts. Instead of opening a chat and typing a prompt yourself, your code creates the agent, sends the task, streams events, waits for the result, and handles errors.

In this tutorial, we set up the SDK, run a local quickstart, then build the main project: a cloud agent that fixes a bug in a GitHub repo and opens a pull request. I keep the bug small on purpose so the SDK flow stays visible. After that, we cover the extension points and safety checks needed before adapting the pattern. The cloud project uses a companion repo with the launcher script and target project.

The SDK is in public beta, so check the official docs before reusing this code in a long term project.

What Is the Cursor SDK?

The Cursor SDK is a TypeScript package, @cursor/sdk, that lets you create and run Cursor agents from code. It gives you access to:

• Local and cloud agents run.
• Cursor's codebase tools, including indexing, search, grep, MCP servers, skills, hooks, and subagents.
• The models available through your Cursor account, including Composer 2, GPT-5.5, and Claude.

The SDK uses the same agent system as the Cursor IDE, CLI, and web app. The difference is that you call it from TypeScript.

When to use the SDK

The SDK fits tasks that should start from code instead of from a person typing in the editor. I would reach for it for a CI job that asks an agent to inspect a failing test, a webhook that creates a branch for a bug fix, or an internal tool that runs a fixed agent task from a form.

SDK versus the Cursor app

The SDK is another way to use Cursor agents, alongside the Cursor IDE and the cursor agent CLI.

Use the IDE for editor chat. Use the CLI for terminal prompts. Use the SDK when TypeScript code needs to create the agent, send the task, and handle the result. As mentioned above, the CLI does not support external provider keys; the SDK also authenticates through a Cursor API key only.

How the Cursor SDK Fits Together

Before writing code, it helps to know the few objects and runtime choices the SDK exposes.

Cursor SDK architecture across three runtimes. Image by Author.

Three runtimes

The SDK supports three places an agent can run.

In this article, we use local and Cursor cloud. Self hosted cloud, listed above, is mainly for Enterprise plans. The SDK code changes through the config key you pass: local or cloud.

Runtime, tools, and models

A run inside the SDK has three parts. The runtime is where it executes. The agent tools include indexing, search, MCP tool calls, skills, hooks, and subagents. The model is selected with model: { id: "composer-2" } or another id your account can use.

You set these pieces in the agent config.

Agent and Run

The two main objects in the SDK are the Agent and the Run. An agent holds conversation state, workspace config, and model settings. A run is one prompt sent to that agent, with its own stream, status, result, and cancel handle.

The split matters because cloud agents enforce one active run per agent. If you try to send a second prompt while the first is still going, the API returns 409 agent_busy. To run things in parallel, you create separate agents, not separate runs on the same agent.

Streaming events

Every run exposes a stream of events through run.stream(), which is an async iterator. Each event has a type field. In the current public beta, the SDK emits system, user, assistant, tool_call, thinking, status, request, and task events. There is no documented connection:reconnecting event; reconnects are handled inside the SDK.

For lower level updates, agent.send() also accepts onDelta and onStep callbacks.

Setting Up the Cursor SDK

The setup is just Node, TypeScript, and a Cursor API key.

Prerequisites

You need:

• Node.js 22 or newer. The package formally supports Node 18 or newer, but Node 22 matches the official cookbook examples and supports the --env-file flag used below to load .env.

• A Cursor account on Pro ($20/month) or above for cloud agents.

• Basic TypeScript familiarity.

• tsx to run TypeScript without compiling.

Install the SDK and the TypeScript tools:

Install the SDK

In a fresh folder:

npm init -y
npm install @cursor/sdk
npm install --save-dev typescript tsx @types/node

Add "type": "module" to your package.json so the imports work as ESM. Then add a tsconfig.json that supports top level await and explicit async disposal:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022", "ESNext.Disposable"],
    "strict": true,
    "esModuleInterop": true
  }
}

Get a Cursor API key

The key was originally generated under cursor.com/dashboard/cloud-agents, but it has moved to cursor.com/dashboard/integrations. If a guide points to "Cloud Agents," check Integrations instead.

Generate User API Keys from Integrations. Image by Author.

Generate a User API Key from there and store it as CURSOR_API_KEY:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .env

Add .env to your .gitignore. The SDK reads process.env directly; it does not load .env files for you.

Project structure

Folder layout: package.json, tsconfig.json, .env, and src/ for your scripts. Add a .cursor/ folder for hooks, skills, and subagents when you need them.

Your First Local Cursor Agent

The first example is intentionally small. It creates a local agent, sends one prompt, streams the response, and disposes the agent.

Create a local agent

Create src/01-quickstart.ts:

import { Agent, type SDKMessage } from "@cursor/sdk";

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

Agent.create() returns a handle before the agent has done any work. local: { cwd: process.cwd() } points the agent at the current working directory. The SDK supports async disposal; in tutorial code, I prefer an explicit finally block because it avoids await using version questions.

Send a prompt and stream the response

Sending a prompt returns a Run object with its own stream and status. This example reads the stream in a for await loop and prints only the assistant text.

try {
  const run = await agent.send(
    `Write a terminal-friendly summary for a screenshot.

Output exactly:
Local agent summary
- Purpose: demonstrates a local Cursor SDK agent.
- Key files: src/01-quickstart.ts, package.json, tsconfig.json.
- SDK action: creates an agent and streams assistant text.

Rules:
Print exactly those three bullets.
No Markdown bold.
No extra explanation.`,
  );

  for await (const event of run.stream()) {
    if (event.type !== "assistant") continue;
    for (const block of event.message.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  }

  const result = await run.wait();
  const duration = result.durationMs === undefined ? "" : `duration=${result.durationMs}ms`;
  console.log(`\n[done] status=${result.status}${duration}`);
} finally {
  await agent[Symbol.asyncDispose]();
}

The agent emits several event types, including thinking, tool_call, and status. This example filters for assistant text because that is the visible answer. event.message.content is typed and usable for streaming, but it is block based and may include tool calls. If you only need final text, skip the stream and read result.result after run.wait(). durationMs is public but optional, so the example handles it as optional.

Handle errors

The SDK throws typed errors that extend CursorAgentError. Common cases include AuthenticationError for a bad key, ConfigurationError for an invalid model id, RateLimitError, IntegrationNotConnectedError, and NetworkError.

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

try {
  // ... agent code
} catch (error) {
  if (error instanceof CursorAgentError) {
    console.error([${error.code ?? "unknown"}] ${error.message});
    if (error.isRetryable) {
      console.error("Retryable. Try again in a moment.");
    }
  } else {
    throw error;
  }
}

The isRetryable flag is what your retry logic should check. Network errors and rate limits are retryable; bad configuration and authentication are not.

Run it

Save the file and run it with Node's .env loader and tsx.

node --env-file=.env --import tsx/esm src/01-quickstart.ts

The --env-file=.env flag loads CURSOR_API_KEY before the script starts. The script should print assistant text, then a one line status footer. If you see an authentication error, check your .env and confirm the key was generated from the Integrations dashboard.