GPT Diffusion

Cursor SDK — Agentes programáticos con TypeScript

2026-05-21 · Tutoriales #cursor#sdk#typescript#agentes#coding-agents#tutorial

TL;DR

  • npm install @cursor/sdk te da acceso al mismo runtime de agentes que usa Cursor IDE, no solo una API de modelo.
  • Tres modos de ejecución: local (iteración rápida), cloud (VMs dedicadas con auto-PR), y self-hosted (red interna).
  • Composer 2.5 (modelo por defecto) rinde ~79.8% en SWE-Bench a $0.50/$2.50 por millón de tokens; comparable a Claude Opus 4.7 a una décima parte del coste.
  • Incluye capacidades nativas: indexado semántico del codebase, MCP, hooks (.cursor/hooks.json) y subagentes.
  • Limitaciones actuales: solo TypeScript, un repo por agente en cloud v1, y estado stateless por defecto.

Contexto

Los coding agents han evolucionado de ser asistentes interactivos dentro de un IDE a infraestructura programable que puedes orquestar desde tus scripts y CI/CD. Cursor lleva años refinando su agente “Composer” dentro de su IDE; con el SDK (lanzado abril 2026, beta pública) expone ese mismo runtime como paquete TypeScript. No estás llamando a una API de modelo; estás importando el harness completo: indexado semántico, gestión de contexto, ejecución sandboxeada y herramientas MCP.

¿Por qué importa ahora? Porque los costes de modelos frontier siguen altos ($15–75 por millón de tokens en Claude Opus) mientras que Composer 2.5 ofrece calidad comparable (~80% SWE-Bench) a $0.50/$2.50. Además, el modelo corre en VMs dedicadas que clonan tu repo y pueden abrir PRs automáticamente — algo que Claude Code SDK (que es una CLI, no un runtime) o OpenAI Agents SDK (model-centered, sin sandbox) no ofrecen out-of-the-box.

1. Instalación y configuración

Necesitas Node.js ≥18 y una API key de Cursor (la misma de tu cuenta de Cursor IDE). El paquete está en npm como @cursor/sdk.

npm install @cursor/sdk

Crea un archivo .env (o configura en tu CI):

CURSOR_API_KEY=tu_key_aqui

Verifica que la API está accesible:

curl -H "Authorization: Bearer $CURSOR_API_KEY" https://api.cursor.sh/v1/models

Deberías obtener una lista de modelos con alias como composer-latest, composer-2, gpt-5.5, etc.

2. Agente local (tu máquina)

El modo local es útil para desarrollo y pruebas rápidas. Aquí un agente que resume el repositorio actual:

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

async function main() {
  const agent = await Agent.create({
    apiKey: process.env.CURSOR_API_KEY!,
    model: { id: "composer-2" },
    local: { cwd: process.cwd() },
  });

  console.log("Agente creado, enviando tarea...");
  const run = await agent.send("¿Qué hace este repo? Resume en 3 frases.");

  for await (const event of run.stream()) {
    if (event.type === "delta") {
      process.stdout.write(event.delta);
    }
    if (event.type === "done") {
      console.log("\n--- RUN FINALIZADA ---");
    }
  }

  await agent.close();
}

main().catch(console.error);

Puntos clave:

  • local.cwd establece el directorio de trabajo; el agente tendrá acceso a tus archivos.
  • run.stream() emite eventos de streaming (deltas de texto, tool calls, completion).
  • Cierra el agente al final para liberar recursos.

Ejecución

ts-node agent-local.ts

O compila con tsc y ejecuta node dist/agent-local.js.

3. Agente en Cursor Cloud (VMs dedicadas)

El modo cloud corre en VMs aisladas que clonan tu repositorio. Tienen ventajas:

  • Persistencia: el agente sigue aunque tu máquina se duerma.
  • Auto-PR: puede abrir pull requests automáticamente.
  • Acceso desde la ventana “Agents Window” de Cursor para takeover manual.

Ejemplo: agente que fija un bug y abre PR:

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

async function fixBug() {
  const agent = await Agent.create({
    apiKey: process.env.CURSOR_API_KEY!,
    model: { id: "composer-2" },
    cloud: {
      repos: [
        {
          url: "https://github.com/tu-org/tu-repo",
          startingRef: "main",
        },
      ],
      autoCreatePR: true,
      environment: {
        // variables de entorno inside VM
        NODE_ENV: "production",
      },
    },
  });

  const run = await agent.send(
    "Analiza el bug reportado en #123. Reproduce el error, encuentra la causa raíz, aplica el fix y abre un PR."
  );

  console.log(`Agente corriendo, ID: ${run.id}`);

  // Puedes desconectar aquí y reconectar después:
  // const result = await (await Agent.getRun(run.id, { runtime: "cloud", agentId: run.agentId })).wait();
  // console.log("PR creado:", result.git?.branches[0]?.prUrl);

  await agent.close();
}

fixBug().catch(console.error);

Detalles:

  • cloud.repos acepta un array de repos (pero en v1 solo se usa el primero).
  • autoCreatePR: true hace que, si el agente hace cambios, intente abrir un PR.
  • Agent.getRun() te permite reconectar a una ejecución en curso o terminada.

4. Subagentes y hooks

El SDK soporta dos patrones avanzados que lo diferencian de mero LLM API.

Subagentes

Puedes delegar subtareas a agentes especializados. Ejemplo: un agente principal que delega “testing” a un subagente con su propio prompt:

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
  subagents: {
    tester: {
      model: { id: "composer-2" },
      instructions: "Eres un QA exhaustivo. Antes de aprobar cualquier cambio, ejecuta tests y verifica cobertura.",
    },
  },
});

const run = await agent.send("Refactoriza utils/auth.ts y que el tester valide antes de commit.");

El agente principal puede invocar @tester como herramienta internamente (el harness lo maneja).

Hooks

Los hooks (.cursor/hooks.json) te permiten observar o interceptar el loop del agente. Por ejemplo, para bloquear pushes a main:

{
  "preRun": ["node scripts/require-pr-review.js"],
  "postToolCall": ["node scripts/log-tools.js"]
}

require-pr-review.js podría lanzar error si el agente intenta modificar ramas protegidas. Los hooks son poderosos pero requieren cuidado: un hook mal escrito puede bloquear al agente en bucle infinito.

5. MCP (Model Context Protocol)

El SDK carga servidores MCP definidos en .cursor/mcp.json (o inline en la configuración del agente). Esto permite conectar el agente a tus herramientas internas:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "jira": {
      "url": "https://tua-organizacion.atlassian.net",
      "type": "http"
    }
  }
}

Con eso, el agente puede leer issues de GitHub/Jira, crear tickets, etc. El SDK inyecta las herramientas MCP automáticamente en el loop.

6. Comparación con Claude Code SDK y OpenAI Agents SDK

CaracterísticaCursor SDKClaude Code SDK (beta)OpenAI Agents SDK
LenguajeTypeScript (Node)TypeScript/CLIPython
Modelo por defectoComposer 2.5 (cursor-specific)Claude Sonnet 4GPT-4.5 / otros
Sandbox VMSí (cloud dedicada)No (local/cli)No
Indexado semántico codebaseSí, nativoNo (solo repo browser)No
Auto-PRSíNo (pero puede sugerir diff)No
MCPSíNoNo (permiten tool calling custom)
SubagentesSíSí (delegation)Sí
Pricing (entrada/salida por 1M tokens)~$0.50 / ~$2.50~$3 / ~$15 (Sonnet)~$2.50 / ~$10 (GPT-4.5)
SWE-Bench approx79.8%~76-78% (Sonnet)~78% (GPT-4.5)
Multi-repo (cloud)1 (v1)N/AN/A
Self-hosted workersSíNoSí (trae tu propia infra)

Observaciones:

  • Calidad/coste: Composer 2.5 está en el mismo rango que GPT-4.5/Claude Sonnet en benchmarks de código pero a coste significativamente menor. Para tareas rutinarias (refactors, revisión de código, generación de tests) es probablemente la mejor opción económica.
  • Infraestructura: Cursor es el único que te da VM + repo clonado + auto-PR. Si necesitas eso, evitas construirlo tú.
  • Language lock: Cursor SDK es TypeScript-only. Si tu stack es Python/Go, tendrías que usar la REST API directamente o esperar bindings oficiales (no anunciados).

7. Costes reales y cuándo compensa

Según la documentación oficial y análisis de Vantage (mayo 2026):

ModeloInput / 1M tokensOutput / 1M tokensSWE-Bench
Composer 2.5$0.50$2.5079.8%
GPT-4.5~$2.50~$10.00~78%
Claude Sonnet 4~$3.00~$15.00~76-78%
Claude Opus 4.7~$15.00~$75.00~80.5%

Mi lectura: Para la mayoría de tareas de coding (scaffolding, generación de código, revisión automática), Composer 2.5 rinde casi al nivel de Opus a 1/10 del coste. La diferencia de ~0.7% en SWE-Bench no justifica el salto de precio salvo que necesites el último 0.5% de calidad en cambios arquitectónicos críticos.

Sin embargo, el coste real de un agente no son solo tokens: el tiempo de VM en cloud se factura también (pero Cursor lo incluye en el token billing según uso). En cargas pesadas (repos muy grandes, muchos archivos), el indexado semántico inicial puede consumir tokens extra, pero luego se cachea.

8. Limitaciones y dolores actuales (beta)

  1. TypeScript-only. Si tu equipo no usa Node, no puedes integrar el SDK directamente. Tendrías que lanzar un proceso hijo que ejecute el agente y communicate via STDIN/OUT o REST — lo que agrega complejidad.
  2. Un repositorio por agente en cloud v1. Si tu flujo necesita tocar múltiples repos (microservicios), tendrás que lanzar agentes separados por repo y coordinar manualmente.
  3. Stateless por defecto. El agente no persiste memoria entre runs a menos que guardes tú el estado (por ejemplo, en Redis) y lo re-inyectes via prompt en la siguiente invocación. Cursor está trabajando en memoria duradera.
  4. Error reporting coarse. Timeouts y refusals de modelo aparecen como errores genéricos. Necesitas logs externos (hooks) para distinguir.
  5. Documentación de orchestración compleja. Los ejemplos oficiales cubren casos simples; patrones multi-agent avanzados (ej: un agente supervisor que decide cuándo hacer fetch de datos externos) los estás descubriendo por tu cuenta.

9. Casos de uso reales que funcionan hoy

Según testimonios en el blog de Cursor (Faire, otras empresas beta):

  • CI/CD autónoma: Cuando un build falla, un webhook dispara un agente; este analiza logs, identifica causa raíz usando indexado semántico, escribe un fix, corre tests locales en la VM, y abre PR si pasa. Reduce tiempo de triage de ~1h a ~10 min.
  • Herramientas internas para negocio: Un equipo de GTM puede solicitar “¿Qué cuota tiene el cliente X?” en Slack; un bot lanza un agente que busca en la base de datos interna (via MCP), resume y responde. Sin necesidad de construir un chatbot custom con knowledge base.
  • Migraciones de frameworks: Agente que lee tu código AngularJS, genera plan de migración a React, implementa página por página, y abre PRs iterativos. El indexado semántico ayuda a entender couplings cross-file.

10. ¿Claude Code SDK o OpenAI Agents SDK?

Si ya estás en el ecosistema de Anthropic o OpenAI, podrías considerar sus SDKs. También he cubierto estos temas con más detalle: prompts y workflows para Claude Code, tu primer agente con OpenAI Agents SDK y cómo recortar costes de coding agents un 50%.

  • Claude Code SDK (lanzamiento 2026, beta): Es principalmente una CLI (claude-code) y una librería TypeScript para lanzar agentes con el modelo de Anthropic. Carece de sandbox VM y indexado semántico integrado; tú tienes que pasar el contexto manualmente. Su ventaja: acceso directo a Claude Opus 4.7 sin intermediario.
  • OpenAI Agents SDK (Python): Similar: te da un loop de agencia con herramientas y memory, pero sin sandbox. Puedes ejecutar en tu propia infra, pero tienes que gestionar el entorno (Docker, file access) tú.

Recomendación práctica:

  • Si ya usas Cursor IDE y quieres agentes programáticos que trabajen sobre tus repos → Cursor SDK.
  • Si necesitas open-weight models (Llama 4, DeepSeek) y model governance self-hosted → OpenRouter + agente custom (pero no hay SDK tan pulido).
  • Si tu prioridad es calidad frontier y no te importa pagar caro → Claude Opus via API directa o Claude Code SDK (pero asume que tendrás que construir tu propio sandbox si lo necesitas).
  • Si eres Python y no quieres Node → OpenAI Agents SDK (aunque estarás en GPT; no hay Claude ni Cursor models).

Conclusión accionable

El Cursor SDK es actualmente la ruta más rápida para tener coding agents que trabajen sobre un codebase real con indexado semántico, sandbox y auto-PR. No es magia: sigue en beta, tiene limitaciones (TypeScript, 1 repo), pero para un equipo de desarrollo que ya pague Cursor Pro, el coste marginal de usar el SDK es bajo.

Mi lectura: Si vas a construir agentes de coding, empieza con Cursor SDK para prototipar. Si en 3 meses sigues necesitando Python o multi-repo, evalúa migrar a un stack custom con vLLM + MCP servers (pero estarás reconstruyendo lo que Cursor ya da). Para la mayoría de startups que usan Node/TS, el SDK es sweet spot entre calidad y coste.

Fuentes

📖 Artículos relacionados

Tu primer agente con OpenAI Agents SDK paso a paso 2026-04-22 · tutoriales Cursor SDK: análisis del runtime de agentes programáticos 2026-04-17 · devs Desplegar agentes de IA con Cloudflare Workers: guía paso a paso 2026-05-23 · tutoriales
Cargando comentarios...