Cursor SDK-tutorial: Coding-agents draaien met TypeScript

Cursor kondigde eind april 2026 zijn TypeScript-SDK aan en bracht die uit als publieke bèta. Het pakket wordt gepubliceerd als @cursor/sdk en draait vanuit Node-omgevingen zoals scripts, CI-jobs en backendservices.

Het grootste verschil met Cursor in de editor is waar de taak start. In plaats van zelf een chat te openen en een prompt te typen, maakt je code de agent aan, verstuurt de taak, streamt events, wacht op het resultaat en handelt fouten af.

In deze tutorial richten we de SDK in, draaien we een lokale quickstart en bouwen we daarna het hoofdproject: een cloudagent die een bug in een GitHub-repo fixt en een pull request opent. Ik houd de bug bewust klein zodat de SDK-flow zichtbaar blijft. Daarna behandelen we de extensiepunten en safety checks die je nodig hebt voordat je het patroon aanpast. Het cloudproject gebruikt een companion-repo met het launchscript en het doelproject.

De SDK is in publieke bèta, dus check de officiële docs voordat je deze code hergebruikt in een langlopend project.

Wat is de Cursor SDK?

De Cursor SDK is een TypeScript-pakket, @cursor/sdk, waarmee je Cursor-agents vanuit code kunt aanmaken en draaien. Je krijgt toegang tot:

• Lokale en cloud-runs van agents.
• De codebase-tools van Cursor, waaronder indexing, search, grep, MCP-servers, skills, hooks en subagents.
• De modellen die via je Cursor-account beschikbaar zijn, waaronder Composer 2, GPT-5.5 en Claude.

De SDK gebruikt hetzelfde agentsysteem als de Cursor IDE, CLI en webapp. Het verschil is dat je het vanuit TypeScript aanroept.

Wanneer gebruik je de SDK

De SDK past bij taken die vanuit code moeten starten in plaats van door iemand die in de editor typt. Ik zou ’m gebruiken voor een CI-job die een agent vraagt een falende test te inspecteren, een webhook die een branch aanmaakt voor een bugfix, of een interne tool die een vaste agenttaak vanuit een formulier draait.

SDK versus de Cursor-app

De SDK is een andere manier om Cursor-agents te gebruiken, naast de Cursor IDE en de cursor agent CLI.

Gebruik de IDE voor editorchat. Gebruik de CLI voor terminalprompts. Gebruik de SDK wanneer TypeScript-code de agent moet aanmaken, de taak versturen en het resultaat afhandelen. Zoals hierboven genoemd, ondersteunt de CLI geen externe provider keys; de SDK authenticeert ook uitsluitend via een Cursor API-sleutel.

Hoe de Cursor SDK in elkaar zit

Voor je code schrijft, helpt het om de paar objecten en runtimekeuzes te kennen die de SDK blootlegt.

Cursor SDK-architectuur over drie runtimes. Afbeelding door auteur.

Drie runtimes

De SDK ondersteunt drie plekken waar een agent kan draaien.

In dit artikel gebruiken we lokaal en Cursor cloud. Self-hosted cloud, hierboven genoemd, is vooral voor Enterprise-plannen. De SDK-code verandert via de configsleutel die je meegeeft: local of cloud.

Runtime, tools en modellen

Een run binnen de SDK heeft drie delen. De runtime is waar hij draait. De agenttools omvatten indexing, search, MCP-toolcalls, skills, hooks en subagents. Het model selecteer je met model: { id: "composer-2" } of een andere id die je account kan gebruiken.

Je stelt deze onderdelen in via de agentconfig.

Agent en Run

De twee belangrijkste objecten in de SDK zijn de Agent en de Run. Een agent bewaart conversatiestatus, workspaceconfig en modelinstellingen. Een run is één prompt die naar die agent wordt gestuurd, met een eigen stream, status, resultaat en cancel-handle.

Die scheiding is belangrijk omdat cloudagents één actieve run per agent afdwingen. Als je een tweede prompt probeert te sturen terwijl de eerste nog loopt, geeft de API 409 agent_busy terug. Voor parallel draaien maak je aparte agents, niet aparte runs op dezelfde agent.

Events streamen

Elke run biedt een stream van events via run.stream(), een async iterator. Elk event heeft een type-veld. In de huidige publieke bèta stuurt de SDK system, user, assistant, tool_call, thinking, status, request en task events uit. Er is geen gedocumenteerd connection:reconnecting-event; reconnects worden binnen de SDK afgehandeld.

Voor lagere-level updates accepteert agent.send() ook onDelta en onStep callbacks.

De Cursor SDK instellen

De setup is alleen Node, TypeScript en een Cursor API-sleutel.

Vereisten

Je hebt nodig:

• Node.js 22 of nieuwer. Het pakket ondersteunt formeel Node 18 of nieuwer, maar Node 22 komt overeen met de officiële cookbookvoorbeelden en ondersteunt de --env-file-vlag die hieronder wordt gebruikt om .env te laden.

• Een Cursor-account op Pro ($20/maand) of hoger voor cloudagents.

• Basiskennis van TypeScript.

• tsx om TypeScript te draaien zonder te compileren.

Installeer de SDK en de TypeScript-tools:

Installeer de SDK

In een lege map:

npm init -y
npm install @cursor/sdk
npm install --save-dev typescript tsx @types/nodeMogelijk gemaakt door

Voeg "type": "module" toe aan je package.json zodat imports als ESM werken. Voeg daarna een tsconfig.json toe die top-level await en expliciete asynchrone disposals ondersteunt:

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

Haal een Cursor API-sleutel op

De sleutel werd oorspronkelijk gegenereerd onder cursor.com/dashboard/cloud-agents, maar is verplaatst naar cursor.com/dashboard/integrations. Als een gids verwijst naar "Cloud Agents", kijk dan bij Integrations.

Genereer User API Keys via Integrations. Afbeelding door auteur.

Genereer daar een User API Key en sla die op als CURSOR_API_KEY:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .envMogelijk gemaakt door

Voeg .env toe aan je .gitignore. De SDK leest process.env direct; hij laadt geen .env-bestanden voor je.

Projectstructuur

Mapindeling: package.json, tsconfig.json, .env en src/ voor je scripts. Voeg een .cursor/-map toe voor hooks, skills en subagents wanneer je die nodig hebt.

Je eerste lokale Cursor-agent

Het eerste voorbeeld is bewust klein. Het maakt een lokale agent aan, stuurt één prompt, streamt de respons en sluit de agent af.

Maak een lokale agent aan

Maak src/01-quickstart.ts aan:

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() },
});Mogelijk gemaakt door

Agent.create() geeft een handle terug voordat de agent iets heeft gedaan. local: { cwd: process.cwd() } wijst de agent op de huidige werkdirectory. De SDK ondersteunt asynchrone disposal; in tutorialcode geef ik de voorkeur aan een expliciet finally-blok omdat dat await using-versievraagstukken vermijdt.

Stuur een prompt en stream de respons

Een prompt sturen geeft een Run-object terug met een eigen stream en status. Dit voorbeeld leest de stream in een for await-lus en print alleen de assistent-tekst.

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]();
}Mogelijk gemaakt door

De agent stuurt meerdere eventtypes uit, waaronder thinking, tool_call en status. Dit voorbeeld filtert op assistant-tekst omdat dat het zichtbare antwoord is. event.message.content is getypt en bruikbaar voor streaming, maar is block-based en kan toolcalls bevatten. Als je alleen eindtekst nodig hebt, sla de stream dan over en lees result.result na run.wait(). durationMs is publiek maar optioneel, dus het voorbeeld behandelt ’m als optioneel.

Fouten afhandelen

De SDK gooit getypte fouten die CursorAgentError uitbreiden. Veelvoorkomende gevallen zijn AuthenticationError voor een ongeldige sleutel, ConfigurationError voor een ongeldige model-id, RateLimitError, IntegrationNotConnectedError en 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;
  }
}Mogelijk gemaakt door

De isRetryable-vlag is waar je retrylogica op moet letten. Netwerkfouten en rate limits zijn retryable; onjuiste configuratie en authenticatie niet.

Draaien

Sla het bestand op en draai het met de .env-loader van Node en tsx.

node --env-file=.env --import tsx/esm src/01-quickstart.tsMogelijk gemaakt door

De vlag --env-file=.env laadt CURSOR_API_KEY voordat het script start. Het script zou assistent-tekst moeten printen, gevolgd door een statusvoetregel op één lijn. Zie je een authenticatiefout, check dan je .env en bevestig dat de sleutel vanuit het Integrations-dashboard is gegenereerd.