Cursor SDK Tutorial: Coding-Agents mit TypeScript ausführen

Cursor hat sein TypeScript SDK Ende April 2026 angekündigt und als öffentliche Beta veröffentlicht. Das Paket heißt @cursor/sdk und läuft in Node-Umgebungen wie Skripten, CI-Jobs und Backend-Services.

Der entscheidende Unterschied zur Nutzung von Cursor im Editor ist der Startpunkt der Aufgabe. Statt einen Chat zu öffnen und selbst einen Prompt einzugeben, erstellt dein Code den Agenten, sendet die Aufgabe, streamt Events, wartet auf das Ergebnis und behandelt Fehler.

In diesem Tutorial richten wir das SDK ein, führen ein lokales Quickstart-Beispiel aus und bauen dann das Hauptprojekt: einen Cloud-Agenten, der einen Bug in einem GitHub-Repo behebt und einen Pull Request öffnet. Ich halte den Bug bewusst klein, damit der SDK-Flow klar sichtbar bleibt. Danach sehen wir uns die Erweiterungspunkte und Safety-Checks an, die du vor der Anpassung des Musters brauchst. Das Cloud-Projekt nutzt ein Begleit-Repo mit dem Starterskript und dem Zielprojekt.

Das SDK ist in der öffentlichen Beta, also sieh in die offiziellen Docs, bevor du den Code in einem langfristigen Projekt wiederverwendest.

Was ist das Cursor SDK?

Das Cursor SDK ist ein TypeScript-Paket, @cursor/sdk, mit dem du Cursor-Agenten per Code erstellen und ausführen kannst. Es gibt dir Zugriff auf:

• Lokal- und Cloud-Runs von Agenten.
• Die Codebase-Tools von Cursor, inklusive Indexierung, Suche, Grep, MCP-Server, Skills, Hooks und Subagenten.
• Die Modelle deines Cursor-Kontos, darunter Composer 2, GPT-5.5 und Claude.

Das SDK nutzt dasselbe Agentensystem wie die Cursor IDE, die CLI und die Web-App. Der Unterschied ist, dass du es aus TypeScript aufrufst.

Wann du das SDK nutzt

Das SDK passt zu Aufgaben, die aus Code heraus starten sollen statt von einer Person im Editor. Ich würde es z. B. für einen CI-Job nehmen, der einen Agenten einen fehlschlagenden Test untersuchen lässt, für einen Webhook, der einen Branch für einen Bugfix anlegt, oder für ein internes Tool, das eine feste Agentenaufgabe aus einem Formular heraus startet.

SDK versus Cursor-App

Das SDK ist ein weiterer Weg, Cursor-Agenten zu nutzen – neben der Cursor IDE und der cursor agent CLI.

Nutze die IDE für Editor-Chats. Nutze die CLI für Prompts im Terminal. Nutze das SDK, wenn TypeScript-Code den Agenten erstellen, die Aufgabe senden und das Ergebnis verarbeiten soll. Wie oben erwähnt, unterstützt die CLI keine externen Provider-Keys; auch das SDK authentifiziert ausschließlich über einen Cursor-API-Key.

So greift das Cursor SDK ineinander

Bevor du Code schreibst, hilft ein Blick auf die wenigen Objekte und Laufzeitumgebungen, die das SDK bereitstellt.

Cursor SDK Architektur über drei Laufzeiten. Bild: Autor.

Drei Laufzeiten

Das SDK unterstützt drei Orte, an denen ein Agent laufen kann.

In diesem Artikel nutzen wir Lokal und Cursor Cloud. Self hosted Cloud, wie oben gelistet, ist vor allem für Enterprise-Pläne. Die SDK-Konfiguration ändert sich über den Konfigschlüssel, den du übergibst: local oder cloud.

Laufzeit, Tools und Modelle

Ein Run im SDK hat drei Teile. Die Laufzeit legt fest, wo er ausgeführt wird. Die Agenten-Tools umfassen Indexierung, Suche, MCP-Toolaufrufe, Skills, Hooks und Subagenten. Das Modell wählst du mit model: { id: "composer-2" } oder einer anderen ID, die dein Konto nutzen kann.

Diese Bausteine setzt du in der Agenten-Konfiguration.

Agent und Run

Die zwei wichtigsten Objekte im SDK sind Agent und Run. Ein Agent hält den Gesprächsstatus, die Workspace-Config und die Modelleinstellungen. Ein Run ist ein einzelner Prompt an diesen Agenten – mit eigenem Stream, Status, Ergebnis und Cancel-Handle.

Diese Trennung ist wichtig, weil Cloud-Agenten genau einen aktiven Run pro Agenten erlauben. Versuchst du einen zweiten Prompt zu senden, während der erste noch läuft, gibt die API 409 agent_busy zurück. Für Parallellauf brauchst du getrennte Agenten, nicht mehrere Runs auf demselben Agenten.

Streaming-Events

Jeder Run stellt einen Event-Stream über run.stream() bereit, ein asynchroner Iterator. Jedes Event hat ein type-Feld. In der aktuellen öffentlichen Beta emittiert das SDK system, user, assistant, tool_call, thinking, status, request und task Events. Es gibt kein dokumentiertes connection:reconnecting-Event; Reconnects werden im SDK intern gehandhabt.

Für Ereignisse auf niedrigerer Ebene akzeptiert agent.send() auch onDelta- und onStep-Callbacks.

Das Cursor SDK einrichten

Für das Setup brauchst du nur Node, TypeScript und einen Cursor-API-Key.

Voraussetzungen

Du brauchst:

• Node.js 22 oder neuer. Offiziell unterstützt das Paket Node 18 oder neuer, aber Node 22 passt zu den Beispielen aus dem Cookbook und unterstützt das --env-file-Flag unten zum Laden von .env.

• Ein Cursor-Konto auf Pro (20 $/Monat) oder höher für Cloud-Agenten.

• Grundkenntnisse in TypeScript.

• tsx, um TypeScript ohne Kompilieren auszuführen.

Installiere das SDK und die TypeScript-Tools:

SDK installieren

In einem frischen Ordner:

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

Füge "type": "module" in deiner package.json hinzu, damit die Imports als ESM funktionieren. Lege dann eine tsconfig.json an, die Top-Level-await und explizites asynchrones Disposing unterstützt:

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

Cursor-API-Key holen

Der Key wurde ursprünglich unter cursor.com/dashboard/cloud-agents generiert, ist aber umgezogen nach cursor.com/dashboard/integrations. Wenn ein Guide auf „Cloud Agents“ verweist, schau stattdessen bei Integrations.

Erzeuge User API Keys unter Integrations. Bild: Autor.

Erzeuge dort einen User-API-Key und speichere ihn als CURSOR_API_KEY:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .env

Füge .env zu deiner .gitignore hinzu. Das SDK liest process.env direkt; es lädt .env-Dateien nicht für dich.

Projektstruktur

Ordnerlayout: package.json, tsconfig.json, .env und src/ für deine Skripte. Lege bei Bedarf einen .cursor/-Ordner für Hooks, Skills und Subagenten an.

Dein erster lokaler Cursor-Agent

Das erste Beispiel ist bewusst klein. Es erstellt einen lokalen Agenten, sendet einen Prompt, streamt die Antwort und entsorgt den Agenten.

Lokalen Agenten erstellen

Erstelle 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() gibt einen Handle zurück, bevor der Agent irgendetwas tut. local: { cwd: process.cwd() } zeigt den Agenten auf das aktuelle Arbeitsverzeichnis. Das SDK unterstützt asynchrones Disposing; in Tutorial-Code bevorzuge ich einen expliziten finally-Block, um Versionsfragen rund um await using zu vermeiden.

Prompt senden und Antwort streamen

Das Senden eines Prompts liefert ein Run-Objekt mit eigenem Stream und Status. Dieses Beispiel liest den Stream in einer for await-Schleife und druckt nur den 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]();
}

Der Agent emittiert mehrere Event-Typen, darunter thinking, tool_call und status. Dieses Beispiel filtert auf assistant-Text, weil das die sichtbare Antwort ist. event.message.content ist typisiert und für Streaming nutzbar, ist aber blockbasiert und kann Tool-Calls enthalten. Wenn du nur finalen Text brauchst, überspringe den Stream und lies result.result nach run.wait(). durationMs ist öffentlich, aber optional, daher behandelt das Beispiel es optional.

Fehler behandeln

Das SDK wirft typisierte Fehler, die CursorAgentError erweitern. Häufige Fälle sind AuthenticationError für einen ungültigen Key, ConfigurationError für eine falsche Modell-ID, RateLimitError, IntegrationNotConnectedError und 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;
  }
}

Das Flag isRetryable ist das, worauf deine Retry-Logik prüfen sollte. Netzwerkfehler und Ratenlimits sind wiederholbar; fehlerhafte Konfiguration und Authentifizierung nicht.

Ausführen

Speichere die Datei und starte sie mit dem .env-Loader von Node und tsx.

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

Das Flag --env-file=.env lädt CURSOR_API_KEY vor dem Skriptstart. Das Skript sollte Assistant-Text ausgeben und dann eine einzeilige Status-Fußzeile. Wenn du einen Authentifizierungsfehler siehst, prüfe deine .env und bestätige, dass der Key über das Integrations-Dashboard erzeugt wurde.