Cursor ha portato in public beta il suo SDK: un pacchetto npm chiamato @cursor/sdk che permette di creare, lanciare e gestire gli agenti di coding di Cursor da qualsiasi script TypeScript, pipeline CI/CD o prodotto SaaS. L'annuncio iniziale risale al 29 aprile, ma in questa settimana il billing tokenizzato e' diventato lo standard per tutti gli account e il flusso self-hosted e' uscito dalla preview ristretta. La promessa e' la stessa che ha spinto Vercel a integrare l'SDK nei suoi template di deploy: trasformare l'agente di coding da feature di un IDE a infrastruttura programmabile.

Cosa contiene il pacchetto npm

L'installazione e' un comando solo:

npm install @cursor/sdk

Da li' si ha accesso allo stesso harness, agli stessi modelli e allo stesso sistema di skill che gira dentro l'app desktop, dentro la Cursor CLI e dentro la versione web. I modelli supportati includono Composer 2 (il coding model proprietario di Cursor), Claude Opus 4.7, Claude Sonnet 4.6 e GPT-5.5; ognuno con un identificatore esposto via { id: "composer-2" }. Il modello Composer 2 e' di fatto il default consigliato per i task agentici, tarato per usare gli strumenti di Cursor in modo efficiente.

Il primo agente "hello world" sta in poche righe ed esegue il task localmente, usando la working directory corrente:

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("Riassumi cosa fa questo repository");

for await (const event of run.stream()) {
  console.log(event);
}

L'API restituisce uno stream di eventi tipizzati: chiamate a tool, output testuali, diff sui file, errori. Per chi viene dall'OpenAI SDK la forma e' familiare.

L'SDK porta dentro qualsiasi pipeline Node.js le stesse capacita' che fino a oggi erano chiuse nell'app Cursor.

Subagenti, hook, skill: i tre cardini

Il vero salto rispetto a un client API tradizionale e' in tre meccanismi: subagenti, hook e skill.

I subagenti sono agenti nominati con prompt e modello proprio, che l'agente principale puo' invocare tramite il tool Agent. E' il modo idiomatico per separare i ruoli: un agente "reviewer" con Opus 4.7, un agente "writer" con Composer 2 per le modifiche di routine, un agente "shell" con permessi ristretti. Vengono caricati da una directory .cursor/agents/ nel repository.

Gli hook, definiti in .cursor/hooks.json, intercettano i punti chiave del ciclo di vita dell'agente: prima dell'esecuzione di un tool, dopo una scrittura su file, alla fine di un run. Servono per osservabilita' (loggare gli eventi su Datadog), policy (bloccare la scrittura su path proibiti), gating (chiedere approvazione umana prima di un git push). La stessa configurazione vale per agenti in cloud, self-hosted e locali.

Le skill sono ricette riutilizzabili in markdown caricate da .cursor/skills/. Cursor consiglia di definire skill per i pattern ripetitivi del proprio codice (esempio: "come scrivere un nuovo endpoint Express con test") e di esporle automaticamente a tutti gli agenti del repo. La community ha gia' iniziato a pubblicare collezioni su GitHub.

Dove gira l'agente

L'SDK supporta tre modalita' di esecuzione. La modalita' cloud usa le VM sandboxate di Cursor (repository clonato, dipendenze installate, credenziali precaricate) ed e' utile per i job lunghi che non devono bloccare la macchina di sviluppo. La modalita' self-hosted fa girare gli stessi agenti su worker dentro la propria rete: il codice non esce mai dal perimetro aziendale, vincolo richiesto da molte banche e PA. La modalita' locale e' quella mostrata sopra: l'agente lavora nella working directory dell'utente, ideale per il debug.

Per Python, il supporto SDK arrivera' piu' avanti: nella beta attuale chi non usa TypeScript deve chiamare direttamente la Cloud Agents REST API documentata su docs.cursor.com. Esiste pero' un'altra strada: la Cursor CLI, che agli inizi di maggio ha ricevuto comandi cursor agent run e cursor agent watch, permette di spawnare agenti dal terminale senza scrivere codice.

Prezzi e modello di consumo

Il SDK e' a pagamento con la stessa logica di Cursor desktop: fatturazione a token, sui token in ingresso e in uscita di ogni modello. I piani Teams e Individual hanno una quota inclusa e poi consumo, mentre il piano Pro ha gia' integrato l'SDK nel proprio limite di token. Bugbot, lo strumento di code review automatico di Cursor, e' passato a fatturazione usage-based per Teams e Individual a partire dall'8 giugno 2026, segno che l'intera azienda sta convergendo sul modello a consumo.

Il modello Composer 2 e' il default consigliato per i task agentici, con pricing a token sia in cloud sia self-hosted.

Cosa cambia per i team

Tre scenari concreti sono gia' emersi nei primi due giorni di beta. Il primo e' la review automatica delle pull request: collegando un webhook GitHub a una funzione che istanzia un agente con il prompt "verifica la PR rispetto a queste regole interne", molti team stanno sostituendo configurazioni precedenti basate su prompt grezzi. Il secondo e' la generazione di test su delta: ogni commit innesca un job che apre un branch, scrive i test mancanti e propone una PR. Il terzo e' il refactor a tappeto, dove subagenti specializzati lavorano in parallelo su modulo per modulo.

I rumors negativi piu' citati nei forum riguardano due limiti dichiarati. La gestione della concorrenza in cloud per i piani entry-level e' ancora a finestra fissa: massimo 5 run in parallelo. E gli hook, pur potenti, non possono ancora intercettare le chiamate di tool MCP servite da terze parti: questo significa che alcune policy di sicurezza devono passare per la configurazione MCP, non per gli hook stessi.

Cursor promette di chiudere il primo gap nel rilascio stabile previsto entro fine giugno; il secondo, piu' delicato, richiede modifiche al protocollo MCP che Anthropic sta discutendo nella propria specifica ufficiale.

Confronto con Claude Code e Mistral Vibe

Cursor SDK non e' il primo: Claude Code di Anthropic ha gia' un SDK per gli skill custom e Mistral Vibe ha appena lanciato i remote agent. La differenza che gli sviluppatori segnalano e' la maturita' del runtime: Cursor ha alle spalle anni di telemetria sull'editor e il suo Composer 2 e' tarato per usare con efficienza gli strumenti tipici dello sviluppo (grep semantico, indicizzazione del repo, esecuzione di test). Claude Code restituisce risposte piu' raffinate ma e' piu' lento; Mistral Vibe vince sul costo, soprattutto per chi gia' usa Le Chat. Per ora, chi gia' lavora con Cursor desktop ha il percorso piu' semplice: l'SDK fa girare gli stessi agenti che vede aprire la sera nell'IDE.