Tutorial sul Cursor SDK: esegui agenti di coding con TypeScript

Cursor ha annunciato il suo SDK TypeScript a fine aprile 2026 e lo ha rilasciato in beta pubblica. Il pacchetto è pubblicato come @cursor/sdk ed è eseguibile da ambienti Node come script, job di CI e servizi backend.

La principale differenza rispetto all’uso di Cursor nell’editor è il punto di avvio dell’attività. Invece di aprire una chat e digitare tu stesso un prompt, il tuo codice crea l’agente, invia il task, trasmette gli eventi in streaming, attende il risultato e gestisce gli errori.

In questo tutorial configuriamo l’SDK, eseguiamo un quickstart locale, poi costruiamo il progetto principale: un agente cloud che corregge un bug in un repo GitHub e apre una pull request. Tengo il bug piccolo di proposito per mantenere visibile il flusso dell’SDK. Dopo, vediamo i punti di estensione e i controlli di sicurezza necessari prima di adattare il pattern. Il progetto cloud usa un repo di accompagnamento con lo script di lancio e il progetto target.

L’SDK è in beta pubblica, quindi controlla la documentazione ufficiale prima di riutilizzare questo codice in un progetto a lungo termine.

Cos’è il Cursor SDK?

Il Cursor SDK è un pacchetto TypeScript, @cursor/sdk, che ti permette di creare ed eseguire agenti Cursor da codice. Ti dà accesso a:

• Esecuzioni di agenti locali e nel cloud.
• Gli strumenti per codebase di Cursor, inclusi indicizzazione, ricerca, grep, server MCP, skill, hook e subagent.
• I modelli disponibili tramite il tuo account Cursor, tra cui Composer 2, GPT-5.5 e Claude.

L’SDK usa lo stesso sistema di agenti dell’IDE Cursor, della CLI e dell’app web. La differenza è che lo chiami da TypeScript.

Quando usare l’SDK

L’SDK si adatta ai task che dovrebbero partire dal codice invece che da una persona che digita nell’editor. Lo userei per un job di CI che chiede a un agente di ispezionare un test fallito, un webhook che crea un branch per una correzione bug o uno strumento interno che esegue un task fisso dell’agente da un form.

SDK vs app Cursor

L’SDK è un altro modo di usare gli agenti Cursor, insieme all’IDE Cursor e alla cursor agent CLI.

Usa l’IDE per la chat in editor. Usa la CLI per i prompt da terminale. Usa l’SDK quando del codice TypeScript deve creare l’agente, inviare il task e gestire il risultato. Come detto sopra, la CLI non supporta chiavi di provider esterni; anche l’SDK si autentica solo tramite una chiave API di Cursor.

Come si incastra il Cursor SDK

Prima di scrivere codice, è utile conoscere i pochi oggetti e le scelte di runtime esposte dall’SDK.

Architettura del Cursor SDK su tre runtime. Immagine dell’autore.

Tre runtime

L’SDK supporta tre luoghi in cui un agente può essere eseguito.

In questo articolo usiamo locale e Cloud Cursor. Il cloud self-hosted, elencato sopra, è principalmente per i piani Enterprise. Il codice dell’SDK cambia tramite la chiave di config che passi: local oppure cloud.

Runtime, strumenti e modelli

Un’esecuzione nell’SDK ha tre parti. Il runtime è dove viene eseguita. Gli strumenti dell’agente includono indicizzazione, ricerca, chiamate a tool MCP, skill, hook e subagent. Il modello si seleziona con model: { id: "composer-2" } o un altro id che il tuo account può usare.

Imposti questi elementi nella config dell’agente.

Agent e Run

I due oggetti principali dell’SDK sono Agent e Run. Un agente contiene lo stato della conversazione, la config dell’area di lavoro e le impostazioni del modello. Un run è un singolo prompt inviato a quell’agente, con il proprio stream, stato, risultato e handle di annullamento.

La distinzione è importante perché gli agenti cloud impongono un run attivo per agente. Se provi a inviare un secondo prompt mentre il primo è ancora in corso, l’API restituisce 409 agent_busy. Per eseguire in parallelo, crei agenti separati, non run separati sullo stesso agente.

Streaming di eventi

Ogni run espone uno stream di eventi tramite run.stream(), che è un async iterator. Ogni evento ha un campo type. Nell’attuale beta pubblica, l’SDK emette eventi system, user, assistant, tool_call, thinking, status, request e task. Non c’è un evento documentato connection:reconnecting; le riconnessioni sono gestite all’interno dell’SDK.

Per aggiornamenti a livello più basso, agent.send() accetta anche callback onDelta e onStep.

Configurare il Cursor SDK

La configurazione richiede solo Node, TypeScript e una chiave API di Cursor.

Prerequisiti

Ti servono:

• Node.js 22 o superiore. Il pacchetto supporta ufficialmente Node 18 o superiore, ma Node 22 corrisponde agli esempi del cookbook ufficiale e supporta il flag --env-file usato sotto per caricare .env.

• Un account Cursor Pro (20 $/mese) o superiore per gli agenti cloud.

• Familiarità di base con TypeScript.

• tsx per eseguire TypeScript senza compilare.

Installa l’SDK e gli strumenti TypeScript:

Installa l’SDK

In una cartella nuova:

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

Aggiungi "type": "module" al tuo package.json così che gli import funzionino come ESM. Poi aggiungi un tsconfig.json che supporti await a livello top e il dispose asincrono esplicito:

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

Ottieni una chiave API di Cursor

La chiave veniva originariamente generata sotto cursor.com/dashboard/cloud-agents, ma è stata spostata su cursor.com/dashboard/integrations. Se una guida punta a "Cloud Agents", controlla invece Integrations.

Genera User API Keys da Integrations. Immagine dell’autore.

Genera da lì una User API Key e salvala come CURSOR_API_KEY:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .env

Aggiungi .env al tuo .gitignore. L’SDK legge direttamente process.env; non carica i file .env per te.

Struttura del progetto

Struttura cartelle: package.json, tsconfig.json, .env e src/ per i tuoi script. Aggiungi una cartella .cursor/ per hook, skill e subagent quando ti servono.

Il tuo primo agente Cursor locale

Il primo esempio è volutamente piccolo. Crea un agente locale, invia un prompt, trasmette in streaming la risposta ed effettua il dispose dell’agente.

Crea un agente locale

Crea 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() restituisce un handle prima che l’agente abbia fatto qualsiasi lavoro. local: { cwd: process.cwd() } punta l’agente alla directory di lavoro corrente. L’SDK supporta il dispose asincrono; nel codice del tutorial, preferisco un blocco finally esplicito perché evita domande sulla versione di await using.

Invia un prompt e trasmetti la risposta

L’invio di un prompt restituisce un oggetto Run con il proprio stream e stato. Questo esempio legge lo stream in un ciclo for await e stampa solo il testo dell’assistente.

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

L’agente emette diversi tipi di evento, tra cui thinking, tool_call e status. Questo esempio filtra il testo dell’assistant perché è la risposta visibile. event.message.content è tipizzato e utilizzabile per lo streaming, ma è basato su blocchi e può includere chiamate a tool. Se ti serve solo il testo finale, salta lo stream e leggi result.result dopo run.wait(). durationMs è pubblico ma facoltativo, quindi l’esempio lo gestisce come opzionale.

Gestisci gli errori

L’SDK genera errori tipizzati che estendono CursorAgentError. I casi comuni includono AuthenticationError per una chiave non valida, ConfigurationError per un model id non valido, RateLimitError, IntegrationNotConnectedError e 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;
  }
}

Il flag isRetryable è ciò che la tua logica di retry dovrebbe controllare. Gli errori di rete e i rate limit sono ripetibili; configurazione errata e autenticazione no.

Eseguilo

Salva il file ed eseguilo con il loader di .env di Node e tsx.

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

Il flag --env-file=.env carica CURSOR_API_KEY prima che lo script inizi. Lo script dovrebbe stampare il testo dell’assistente, poi un footer di stato su una riga. Se vedi un errore di autenticazione, controlla il tuo .env e conferma che la chiave sia stata generata dalla dashboard Integrations.