Cursor SDK: análisis del runtime de agentes programáticos

TL;DR

• Cursor lanza el @cursor/sdk en TypeScript.
• Permite crear agentes programáticos con el mismo runtime, modelos y harness que el IDE de Cursor.
• Incluye acceso a VMs en la nube sandboxed, hooks y gestión de subagentes.
• No es solo una API wrapper. Es el motor de agentes de Cursor desacoplado del editor.

Contexto

Hasta ahora, Cursor era la mejor herramienta de “Copilot on steroids” porque controlaba la experiencia completa: el editor, el contexto y el modelo. Era una herramienta de consumo. Con el lanzamiento del SDK el 29 de abril, Cursor deja de ser solo un producto para convertirse en una plataforma.

Qué es exactamente el Cursor SDK

No es una simple API para enviar prompts. Es una librería que expone el motor de agentes de Cursor. Lo más relevante:

1. Cloud Agent Runtime

Puedes ejecutar agentes que corren en VMs aisladas de Cursor en la nube. No necesitas infraestructura:

import { Agent } from '@cursor/sdk';

const agent = new Agent({
  model: 'claude-sonnet-4',
  instructions: 'Eres un experto en TypeScript. Refactoriza código siguiendo best practices.',
});

const result = await agent.run({
  input: 'Refactoriza auth.ts para usar dependency injection',
  files: ['./src/auth.ts', './src/types.ts'],
});

El agente tiene acceso a un filesystem virtual, puede ejecutar comandos, y leer/escribir archivos — todo en un sandbox aislado.

2. Hooks

Puedes interceptar el loop del agente con hooks:

agent.on('tool_call', (tool, args) => {
  console.log(`Agent llamó: ${tool}(${JSON.stringify(args)})`);
  // Puedes modificar args o rechazar la llamada
  if (tool === 'shell' && args.command.includes('rm')) {
    throw new Error('Comando peligroso bloqueado');
  }
});

agent.on('response', (response) => {
  // Post-procesamiento
  logToDashboard(response);
});

Esto permite control granular: auditar cada acción del agente, bloquear operaciones peligrosas, y añadir lógica de negocio.

3. Subagentes

Un agente puede spawnear subagentes para tareas específicas:

const mainAgent = new Agent({
  model: 'claude-sonnet-4',
  instructions: 'Orquestador principal. Delega tareas a especialistas.',
  subagents: {
    testWriter: new Agent({
      model: 'gpt-4o-mini',
      instructions: 'Escribe tests unitarios.',
    }),
    reviewer: new Agent({
      model: 'claude-sonnet-4',
      instructions: 'Revisa código buscando bugs y problemas de seguridad.',
    }),
  },
});

El patrón drafter-reviewer (un agente genera, otro revisa) es trivial de implementar con subagentes.

API completa

import { Agent, run } from '@cursor/sdk';

// Configurar
const agent = new Agent({
  model: 'claude-sonnet-4',
  instructions: '...',
  tools: ['file_read', 'file_write', 'shell', 'search'],
  maxIterations: 15,
  timeout: 120000, // 2 min
});

// Ejecutar
const result = await agent.run({
  input: 'Implementa autenticación JWT en Express',
  context: {
    files: ['./src/server.ts'],
    repoStructure: true, // Agent ve la estructura del repo
  },
});

// Resultado
console.log(result.output); // Respuesta del agente
console.log(result.filesChanged); // Lista de archivos modificados
console.log(result.tokensUsed); // Tokens consumidos
console.log(result.iterations); // Número de iteraciones

Casos de uso

1. CI/CD integration

Ejecuta agentes de Cursor como paso de CI:

// En tu GitHub Action
const reviewer = new Agent({
  model: 'claude-sonnet-4',
  instructions: 'Revisa el PR buscando bugs, problemas de seguridad y mejoras.',
});

const result = await reviewer.run({
  input: 'Revisa los cambios de este PR',
  context: { diff: process.env.PR_DIFF },
});

if (result.output.includes('CRITICAL')) {
  process.exit(1); // Fail the CI
}

2. Automated code generation

Genera código repetitivo con agentes:

const generator = new Agent({
  model: 'gpt-4o-mini', // Barato para tareas repetitivas
  instructions: 'Genera CRUD endpoints a partir de un schema Prisma.',
});

for (const model of prismaModels) {
  await generator.run({
    input: `Genera endpoints CRUD para ${model}`,
    context: { prismaSchema: schema },
  });
}

3. Batch refactoring

Refactoriza en batch con revisión automática:

const refactoringAgent = new Agent({
  model: 'claude-sonnet-4',
  instructions: 'Migra de JavaScript a TypeScript. Mantén la funcionalidad.',
});

// Procesar archivo por archivo
for (const file of jsFiles) {
  const result = await refactoringAgent.run({
    input: `Migra ${file} a TypeScript`,
    context: { files: [file] },
  });

  // Revisar automáticamente
  if (!result.testsPass) {
    console.error(`Refactoring falló para ${file}`);
    break;
  }
}

Precios

El SDK usa tu propia API key. No hay coste adicional de Cursor:

• Los modelos se cobran a tarifa normal del proveedor
• Las Cloud VMs tienen un free tier (100 horas/mes)
• Sin coste por la librería本身

Comparación con alternativas

Feature	Cursor SDK	Claude Code	Codex CLI	OpenCode
Runtime	Cloud VM + local	Local	Sandbox GitHub	Local
Language	TypeScript	CLI	CLI	Go/CLI
Subagents	✅ Built-in	❌	⚠️ Básico	❌
Hooks	✅ Granular	❌	❌	❌
Open source	❌	❌	❌	✅
IDE integration	Cursor IDE	Terminal	GitHub	Terminal

Limitaciones

No es open-source. No puedes auditar el runtime. Confías en que Cursor hace lo que dice.

Vendor lock-in. El SDK está ligado al ecosistema de Cursor. Si Cursor cambia precios o features, estás atado.

Cloud VMs tienen límites. 100 horas/mes gratis, después de pago. Para uso intensivo, tu propia infra puede ser más barata.

Model support limitado. Solo modelos que Cursor soporta (Claude, GPT, Gemini). No puedes usar modelos custom o local.

Conclusión

El Cursor SDK es significativo porque democratiza el motor de agentes que hace que Cursor sea bueno. Ya no necesitas el editor — puedes usar el mismo runtime programáticamente.

Para equipos que ya usan Cursor, el SDK es una extensión natural. Para otros, OpenCode o Claude Code pueden ser más apropiados según el caso.

Lo más interesante: los hooks y subagentes. Estos primitivos permiten patrones de agent orchestration que antes requerían frameworks pesados (LangGraph, CrewAI). Con el SDK de Cursor, la implementación es directa.

---

Fuentes: Cursor SDK docs, @cursor/sdk npm package, experiencia personal.