Tutorial del SDK de Cursor: ejecuta agentes de código con TypeScript

Cursor anunció su SDK de TypeScript a finales de abril de 2026 y lo lanzó como beta pública. El paquete se publica como @cursor/sdk y se ejecuta desde entornos Node, como scripts, trabajos de CI y servicios backend.

La gran diferencia respecto a usar Cursor en el editor es dónde empieza la tarea. En lugar de abrir un chat y escribir un prompt tú mismo, tu código crea el agente, envía la tarea, hace streaming de eventos, espera el resultado y gestiona errores.

En este tutorial, configuramos el SDK, ejecutamos un quickstart local y luego construimos el proyecto principal: un agente en la nube que corrige un bug en un repositorio de GitHub y abre un pull request. Mantengo el bug pequeño a propósito para que el flujo del SDK se vea claro. Después, cubrimos los puntos de extensión y las comprobaciones de seguridad necesarias antes de adaptar el patrón. El proyecto en la nube usa un repo complementario con el script lanzador y el proyecto objetivo.

El SDK está en beta pública, así que revisa la documentación oficial antes de reutilizar este código en un proyecto a largo plazo.

¿Qué es el SDK de Cursor?

El SDK de Cursor es un paquete de TypeScript, @cursor/sdk, que te permite crear y ejecutar agentes de Cursor desde código. Te da acceso a:

• Ejecuciones de agentes locales y en la nube.
• Las herramientas de codebase de Cursor, como indexación, búsqueda, grep, servidores MCP, skills, hooks y subagentes.
• Los modelos disponibles en tu cuenta de Cursor, incluidos Composer 2, GPT-5.5 y Claude.

El SDK usa el mismo sistema de agentes que el IDE de Cursor, la CLI y la app web. La diferencia es que lo invocas desde TypeScript.

Cuándo usar el SDK

El SDK encaja en tareas que deben iniciarse desde código en lugar de por una persona tecleando en el editor. Yo lo usaría para un trabajo de CI que pida a un agente inspeccionar un test fallido, un webhook que cree una rama para un bugfix o una herramienta interna que ejecute una tarea fija de agente desde un formulario.

SDK frente a la app de Cursor

El SDK es otra forma de usar agentes de Cursor, junto al IDE de Cursor y la cursor agent CLI.

Usa el IDE para chatear en el editor. Usa la CLI para prompts en la terminal. Usa el SDK cuando código en TypeScript necesite crear el agente, enviar la tarea y manejar el resultado. Como se mencionó arriba, la CLI no admite claves de proveedores externos; el SDK también se autentica solo mediante una clave API de Cursor.

Cómo encaja el SDK de Cursor

Antes de escribir código, ayuda conocer los pocos objetos y elecciones de runtime que expone el SDK.

Arquitectura del SDK de Cursor en tres runtimes. Imagen del autor.

Tres runtimes

El SDK admite tres lugares donde puede ejecutarse un agente.

En este artículo usamos local y la nube de Cursor. La nube autogestionada, listada arriba, es principalmente para planes Enterprise. El código del SDK cambia mediante la clave de configuración que pasas: local o cloud.

Runtime, herramientas y modelos

Una ejecución dentro del SDK tiene tres partes. El runtime es dónde se ejecuta. Las herramientas del agente incluyen indexación, búsqueda, llamadas a herramientas MCP, skills, hooks y subagentes. El modelo se selecciona con model: { id: "composer-2" } u otro id que tu cuenta pueda usar.

Configuras estas piezas en la configuración del agente.

Agent y Run

Los dos objetos principales del SDK son Agent y Run. Un agente guarda el estado de la conversación, la configuración del workspace y los ajustes del modelo. Un run es un prompt enviado a ese agente, con su propio stream, estado, resultado y handle de cancelación.

Esta separación importa porque los agentes en la nube fuerzan un run activo por agente. Si intentas enviar un segundo prompt mientras el primero sigue en curso, la API devuelve 409 agent_busy. Para ejecutar en paralelo, crea agentes separados, no runs separados sobre el mismo agente.

Eventos en streaming

Cada run expone un stream de eventos mediante run.stream(), que es un iterador asíncrono. Cada evento tiene un campo type. En la beta pública actual, el SDK emite eventos system, user, assistant, tool_call, thinking, status, request y task. No hay un evento documentado connection:reconnecting; las reconexiones se gestionan dentro del SDK.

Para actualizaciones de más bajo nivel, agent.send() también acepta callbacks onDelta y onStep.

Configurar el SDK de Cursor

La configuración es solo Node, TypeScript y una clave API de Cursor.

Requisitos previos

Necesitas:

• Node.js 22 o superior. El paquete admite oficialmente Node 18 o superior, pero Node 22 coincide con los ejemplos del cookbook oficial y admite la flag --env-file que usamos abajo para cargar .env.

• Una cuenta de Cursor Pro ($20/mes) o superior para agentes en la nube.

• Conocimientos básicos de TypeScript.

• tsx para ejecutar TypeScript sin compilar.

Instala el SDK y las herramientas de TypeScript:

Instala el SDK

En una carpeta nueva:

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

Añade "type": "module" a tu package.json para que las importaciones funcionen como ESM. Luego añade un tsconfig.json que admita await a nivel superior y liberación asíncrona explícita:

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

Consigue una clave API de Cursor

La clave se generaba originalmente en cursor.com/dashboard/cloud-agents, pero se ha movido a cursor.com/dashboard/integrations. Si una guía apunta a "Cloud Agents", comprueba Integrations.

Genera User API Keys desde Integrations. Imagen del autor.

Genera una User API Key allí y guárdala como CURSOR_API_KEY:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .env

Añade .env a tu .gitignore. El SDK lee process.env directamente; no carga archivos .env por ti.

Estructura del proyecto

Estructura de carpetas: package.json, tsconfig.json, .env y src/ para tus scripts. Añade una carpeta .cursor/ para hooks, skills y subagentes cuando los necesites.

Tu primer agente local de Cursor

El primer ejemplo es intencionadamente pequeño. Crea un agente local, envía un prompt, hace streaming de la respuesta y libera el agente.

Crea un agente local

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() devuelve un handle antes de que el agente haya hecho ningún trabajo. local: { cwd: process.cwd() } apunta el agente al directorio de trabajo actual. El SDK admite liberación asíncrona; en un tutorial prefiero un bloque finally explícito porque evita dudas sobre await using y versiones.

Envía un prompt y haz streaming de la respuesta

Enviar un prompt devuelve un objeto Run con su propio stream y estado. Este ejemplo lee el stream en un bucle for await e imprime solo el texto del asistente.

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

El agente emite varios tipos de evento, como thinking, tool_call y status. Este ejemplo filtra por texto del assistant porque es la respuesta visible. event.message.content está tipado y es utilizable para streaming, pero es por bloques y puede incluir llamadas a herramientas. Si solo necesitas el texto final, omite el stream y lee result.result tras run.wait(). durationMs es pública pero opcional, por eso el ejemplo la trata como opcional.

Gestiona errores

El SDK lanza errores tipados que extienden CursorAgentError. Casos comunes incluyen AuthenticationError por una clave errónea, ConfigurationError por un id de modelo inválido, RateLimitError, IntegrationNotConnectedError y 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;
  }
}

La marca isRetryable es lo que debe comprobar tu lógica de reintentos. Los errores de red y los límites de ritmo son reintentables; la configuración incorrecta y la autenticación, no.

Ejecútalo

Guarda el archivo y ejecútalo con el cargador de .env de Node y tsx.

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

La flag --env-file=.env carga CURSOR_API_KEY antes de que empiece el script. El script debería imprimir el texto del asistente y luego un pie de estado en una línea. Si ves un error de autenticación, comprueba tu .env y confirma que la clave se generó desde el panel de Integrations.