Tutoriel Cursor SDK : exécuter des agents de code avec TypeScript

Cursor a annoncé son SDK TypeScript fin avril 2026 et l'a publié en bêta publique. Le package est publié sous @cursor/sdk et s'exécute depuis des environnements Node : scripts, jobs CI et services backend.

La principale différence avec l'usage de Cursor dans l'éditeur tient au point de départ de la tâche. Au lieu d'ouvrir un chat et de saisir vous-même une invite, votre code crée l'agent, envoie la tâche, streame les événements, attend le résultat et gère les erreurs.

Dans ce tutoriel, nous configurons le SDK, exécutons un démarrage rapide en local, puis construisons le projet principal : un agent cloud qui corrige un bug dans un dépôt GitHub et ouvre une pull request. Je garde le bug volontairement mineur pour que le flux du SDK reste lisible. Ensuite, nous couvrons les points d'extension et les contrôles de sécurité nécessaires avant d'adapter le schéma. Le projet cloud utilise un référentiel compagnon avec le script de lancement et le projet cible.

Le SDK est en bêta publique : consultez la documentation officielle avant de réutiliser ce code dans un projet de long terme.

Qu'est-ce que le Cursor SDK ?

Le Cursor SDK est un package TypeScript, @cursor/sdk, qui vous permet de créer et d'exécuter des agents Cursor depuis du code. Il donne accès à :

• Des exécutions d'agents en local et dans le cloud.
• Les outils de base de code de Cursor, dont l'indexation, la recherche, grep, les serveurs MCP, les skills, les hooks et les sous-agents.
• Les modèles disponibles via votre compte Cursor, dont Composer 2, GPT-5.5 et Claude.

Le SDK utilise le même système d'agents que l'IDE Cursor, le CLI et l'application web. La différence : vous l'appelez depuis TypeScript.

Quand utiliser le SDK

Le SDK convient aux tâches qui doivent démarrer depuis du code plutôt que depuis une saisie humaine dans l'éditeur. Je l'utiliserais pour un job CI qui demande à un agent d'inspecter un test en échec, un webhook qui crée une branche pour un correctif, ou un outil interne qui exécute une tâche d'agent fixe depuis un formulaire.

SDK versus l'app Cursor

Le SDK est une autre façon d'utiliser les agents Cursor, aux côtés de l'IDE Cursor et du cursor agent CLI.

Utilisez l'IDE pour discuter dans l'éditeur. Utilisez le CLI pour des invites au terminal. Utilisez le SDK lorsque du code TypeScript doit créer l'agent, envoyer la tâche et gérer le résultat. Comme indiqué plus haut, le CLI ne prend pas en charge des clés de fournisseurs externes ; le SDK s'authentifie également uniquement via une clé API Cursor.

Comment s'articule le Cursor SDK

Avant d'écrire du code, il est utile de connaître les quelques objets et choix d'exécution que le SDK expose.

Architecture du Cursor SDK sur trois environnements d'exécution. Image de l'auteur.

Trois environnements d'exécution

Le SDK prend en charge trois lieux d'exécution pour un agent.

Dans cet article, nous utilisons local et Cursor cloud. Le cloud auto-hébergé, listé ci-dessus, vise surtout les offres Enterprise. Le code SDK varie selon la clé de config passée : local ou cloud.

Runtime, outils et modèles

Une exécution dans le SDK a trois composantes. Le runtime est le lieu d'exécution. Les outils d'agent incluent indexation, recherche, appels d'outils MCP, skills, hooks et sous-agents. Le modèle se sélectionne avec model: { id: "composer-2" } ou un autre id disponible pour votre compte.

Vous définissez ces éléments dans la config de l'agent.

Agent et Run

Les deux principaux objets du SDK sont Agent et Run. Un agent conserve l'état de la conversation, la config de l'espace de travail et les paramètres du modèle. Un run est une invite envoyée à cet agent, avec son propre stream, statut, résultat et handle d'annulation.

Cette séparation est importante car les agents cloud imposent un run actif par agent. Si vous tentez d'envoyer une seconde invite pendant la première, l'API renvoie 409 agent_busy. Pour exécuter en parallèle, créez des agents distincts, pas des runs distincts sur le même agent.

Streaming des événements

Chaque run expose un flux d'événements via run.stream(), qui est un itérateur asynchrone. Chaque événement a un champ type. Dans la bêta publique actuelle, le SDK émet system, user, assistant, tool_call, thinking, status, request et task. Il n'y a pas d'événement documenté connection:reconnecting ; les reconnexions sont gérées en interne par le SDK.

Pour des mises à jour de plus bas niveau, agent.send() accepte aussi des callbacks onDelta et onStep.

Configuration du Cursor SDK

La mise en place se limite à Node, TypeScript et une clé API Cursor.

Prérequis

Vous avez besoin :

• De Node.js 22 ou plus récent. Le package prend officiellement en charge Node 18 ou plus, mais Node 22 correspond aux exemples du cookbook officiel et prend en charge l'option --env-file utilisée ci-dessous pour charger .env.

• D'un compte Cursor Pro (20 $/mois) ou plus pour les agents cloud.

• De notions de base en TypeScript.

• tsx pour exécuter du TypeScript sans compilation.

Installez le SDK et les outils TypeScript :

Installer le SDK

Dans un nouveau dossier :

npm init -y
npm install @cursor/sdk
npm install --save-dev typescript tsx @types/nodePropulsé par

Ajoutez "type": "module" dans votre package.json pour que les imports fonctionnent en ESM. Puis ajoutez un tsconfig.json qui prend en charge await au niveau supérieur et la libération asynchrone explicite :

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

Obtenir une clé API Cursor

La clé était initialement générée sous cursor.com/dashboard/cloud-agents, mais elle a déménagé vers cursor.com/dashboard/integrations. Si un guide renvoie à "Cloud Agents", regardez plutôt Intégrations.

Générez des User API Keys depuis Intégrations. Image de l'auteur.

Générez une User API Key à partir de là et stockez-la sous CURSOR_API_KEY :

echo 'CURSOR_API_KEY=crsr_your_key_here' > .envPropulsé par

Ajoutez .env à votre .gitignore. Le SDK lit process.env directement ; il ne charge pas les fichiers .env pour vous.

Structure du projet

Arborescence : package.json, tsconfig.json, .env et src/ pour vos scripts. Ajoutez un dossier .cursor/ pour les hooks, skills et sous-agents quand vous en avez besoin.

Votre premier agent Cursor local

Le premier exemple est volontairement minimal. Il crée un agent local, envoie une invite, streame la réponse, puis libère l'agent.

Créer un agent local

Créez 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() },
});Propulsé par

Agent.create() renvoie un handle avant que l'agent ne fasse quoi que ce soit. local: { cwd: process.cwd() } pointe l'agent vers le répertoire de travail courant. Le SDK prend en charge la libération asynchrone ; dans un tutoriel, je préfère un bloc finally explicite pour éviter les questions de version autour de await using.

Envoyer une invite et streamer la réponse

Envoyer une invite renvoie un objet Run avec son propre flux et son statut. Cet exemple lit le flux dans une boucle for await et n'affiche que le texte de l'assistant.

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

L'agent émet plusieurs types d'événements, notamment thinking, tool_call et status. Cet exemple filtre le texte assistant car c'est la réponse visible. event.message.content est typé et exploitable pour le streaming, mais il est basé sur des blocs et peut inclure des appels d'outils. Si vous n'avez besoin que du texte final, ignorez le flux et lisez result.result après run.wait(). durationMs est public mais optionnel, donc l'exemple le gère comme tel.

Gérer les erreurs

Le SDK lève des erreurs typées qui étendent CursorAgentError. Les cas courants incluent AuthenticationError pour une mauvaise clé, ConfigurationError pour un id de modèle invalide, RateLimitError, IntegrationNotConnectedError et 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;
  }
}Propulsé par

Le drapeau isRetryable est celui que votre logique de retry doit vérifier. Les erreurs réseau et de rate limit sont réessayables ; une mauvaise configuration ou une authentification invalide ne le sont pas.

Lancer l'exécution

Enregistrez le fichier et exécutez-le avec le chargeur .env de Node et tsx.

node --env-file=.env --import tsx/esm src/01-quickstart.tsPropulsé par

L'option --env-file=.env charge CURSOR_API_KEY avant le démarrage du script. Le script doit afficher le texte de l'assistant, puis un pied de page de statut sur une ligne. Si vous voyez une erreur d'authentification, vérifiez votre .env et confirmez que la clé a été générée depuis le tableau de bord Intégrations.