Skip to main content

Command Palette

Search for a command to run...

Notas de la versión

Notas de la versión del SDK de Cursor

Las últimas funciones, mejoras y soluciones que llegan al SDK de Cursor, tanto para @cursor/sdk en npm como para cursor-sdk en PyPI.

AllAgents WindowIDECursor CLICursor SDK

1.0.35

  • Las herramientas personalizadas saben qué sesión las llamó. El callback execute de una entrada de local.customTools ahora recibe context.sessionId, la sesión local que invocó la herramienta. Los subagentes iniciados con Task pasan su propio id, de modo que un host puede mantener un estado independiente para cada agente hijo. Solo en TypeScript; no se establece si el entorno de ejecución no tiene id de sesión.
  • Correcciones en agentes locales y tipos de TypeScript. Los agentes locales ahora funcionan en hosts con FIPS activado, y los almacenes de agentes locales existentes se trasladan automáticamente a la nueva ubicación. Los agentes restaurados desde el mismo proceso o la misma instantánea de VM ya no reutilizan los IDs de solicitud y de sesión, así que las ejecuciones simultáneas ya no entran en conflicto ni se bloquean. Las declaraciones de tipo de LocalSubagentInherit ahora se resuelven sin depender de un paquete interno no publicado, gracias a los nuevos tipos exportados LocalSubagentResourceProviderFields y LocalToolExecutor.

1.0.34

  • Los subagentes pueden heredar los executors y los límites de herramientas del agente principal. Establece local.subagentInherit para que los agentes iniciados por la herramienta Task, incluidos los anidados, usen los mismos executors personalizados de lectura, escritura y shell, la misma ruta de espacio de trabajo notificada que el agente principal y las mismas herramientas permitidas y excluidas. Pásalo en Agent.create() o anúlalo para un único send. Solo para agentes locales de TypeScript. Si no lo estableces, los subagentes se comportan como antes.
  • Se corrigió el bloqueo de solicitudes por conexiones perdidas en agentes de larga duración. Cuando un agente permanece inactivo entre ejecuciones, el SDK ahora cierra las conexiones HTTP/2 sin usar tras 29 segundos. Además, comprueba las conexiones que llevan aproximadamente un minuto inactivas antes de reutilizarlas. Las solicitudes ya no se escriben en una conexión que el servidor ya ha cerrado, donde antes se quedaban bloqueadas hasta que el tiempo de espera por bloqueo las cancelaba.
  • Las conexiones bloqueadas admiten reintentos con límite. Cuando una conexión se bloquea, la ejecución falla con un NetworkError reintentable con el código connection_stalled, y una racha de reintentos por bloqueo se detiene tras 3 minutos en lugar de reintentarse indefinidamente.
  • Menos dependencias instaladas con el SDK. Instalar @cursor/sdk ya no añade @connectrpc/connect-node ni undici 5.x al árbol de dependencias de tu proyecto, por lo que las instalaciones ocupan menos y ya no aparecen conflictos de versiones ni advertencias de auditoría de esos paquetes.

1.0.32

  • Guía a un agente mientras espera a subagentes en segundo plano. Antes, run.steer(text) se resolvía con revert_to_followup cuando el agente había terminado su interacción para esperar a subagentes en segundo plano, por lo que tu mensaje no se procesaba hasta que ese trabajo terminara. Ahora la indicación se ejecuta de inmediato como la siguiente interacción, y los resultados en segundo plano siguen llegando después. Solo para ejecuciones locales en TypeScript.
  • Detecta cuándo un paso ha terminado de solicitar herramientas. onDelta ahora recibe una actualización tool-requests-listed con un callCount en cuanto el modelo termina de enumerar sus llamadas a herramientas de un paso, aunque esas herramientas sigan ejecutándose. Úsala para saber cuándo se han iniciado todas las llamadas a herramientas de un paso; por ejemplo, para agruparlas o procesarlas en lote en tu interfaz.
  • Correcciones en la creación de agentes en la nube. En los agentes en la nube, el primer send(), que crea el agente en el servidor, ya no falla por un conflicto de id cuando el id del agente lo generó el SDK: reintenta con un id nuevo o continúa con el agente si su propio intento de creación anterior ya se había completado correctamente. Además, los ids de agentes y ejecuciones generados por el SDK ya no se repiten cuando un proceso se restaura desde la misma instantánea más de una vez. Si fijas los ids tú mismo, se sigue notificando el conflicto.
  • El bridge ignora los archivos .env y bunfig.toml de tu proyecto. Los ejecutables independientes de cursor-sdk-bridge ya no cargan .env ni bunfig.toml desde el directorio de trabajo, que suele ser tu proyecto cuando el SDK inicia el bridge. Los archivos de un checkout ya no pueden modificar los endpoints, los tokens ni el código precargado del bridge.

1.0.31

  • Los subagentes en segundo plano devuelven su resultado. Cuando el agente ejecuta un subagente en segundo plano, su resultado ahora vuelve al agente principal como una interacción de seguimiento dentro de la misma ejecución, en lugar de descartarse al terminar la interacción del agente principal. run.stream() sigue emitiendo eventos durante esas interacciones y run.wait() se resuelve cuando estas terminan. Disponible para agentes locales, en TypeScript y Python.
  • Anotaciones en herramientas personalizadas. annotations en una entrada de local.customTools transmite al modelo las anotaciones de herramientas MCP (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Son solo indicaciones descriptivas; el SDK no obliga a cumplirlas. Solo para TypeScript.

1.0.30

  • Los agentes locales de larga duración mantienen sus credenciales actualizadas. Las ejecuciones locales en TypeScript y Python renuevan el token de acceso de corta duración antes de que caduque, por lo que los agentes que se ejecutan durante más de una hora ya no fallan por errores de autenticación. Las ejecuciones en Cloud no se ven afectadas.

1.0.29

  • Esquemas de salida en herramientas personalizadas. outputSchema en TypeScript y output_schema en Python declaran un JSON Schema para el resultado estructurado de una herramienta personalizada, que se expone al modelo como el esquema de salida MCP de la herramienta. Los resultados no se validan contra este esquema. Solo para agentes locales.

1.0.28

  • El SDK se distribuye como un único archivo. En Bun, @cursor/sdk ahora se resuelve en un bundle plano de un único archivo, por lo que bun build --compile funciona sin cambiar ninguna importación y ya no aparece el error Cannot find module './986.js'. @cursor/sdk/bundled y @cursor/sdk/bundled/sqlite exponen la misma compilación como entradas explícitas para otros bundlers de un único archivo, como esbuild. Solo para TypeScript.

1.0.27

  • Restringe el conjunto de herramientas del agente. tools define una lista de permitidos con las herramientas integradas que se ofrecen al modelo ([] significa solo texto), y disallowedTools excluye herramientas concretas y mantiene el resto. Ambos aceptan nombres públicos como "read" o grupos de funcionalidades como "shell" y "mcp", en TypeScript y Python (tools, disallowed_tools). Por ahora, solo para agentes locales, y no se conserva al usar resume.
  • Inicia sesión desde el navegador en TypeScript. Cursor.auth.login() abre un inicio de sesión en el navegador, genera una clave de API y la guarda en ~/.cursor/sdk/auth.json; Cursor.auth.status() y Cursor.auth.logout() completan el conjunto. Tras el login, Agent.create() y las lecturas de Cursor.* funcionan sin apiKey ni CURSOR_API_KEY.
  • Consumo y coste de los agentes locales. agent.getUsage() en TypeScript y agent.get_usage() en Python ahora también funcionan con agentes locales y devuelven un desglose por interacción. Pasa un runId de un resultado anterior para limitarlo a una sola interacción.
  • Abre PR como la Cursor GitHub App. cloud.openAsCursorGithubApp en TypeScript y open_as_cursor_github_app en Python controlan la autoría de los PR. De forma predeterminada, las claves de cuentas de servicio usan la aplicación y las claves de usuario, al propietario de la clave.
  • Espacios de trabajo locales con varias raíces. Pasa local.dirs para cargar reglas, skills y contexto del proyecto desde varias carpetas; cwd sigue siendo el único directorio de trabajo principal. Sustituye a la forma de array de cwd, que en la práctica solo usaba la primera entrada.
  • Errores de Python más claros. Los fallos que antes aparecían simplemente como "internal error" ahora incluyen el mensaje y el código subyacentes.
  • Admin Las listas de denegación de comandos del administrador se aplican a las ejecuciones locales. Los comandos de shell que coinciden con la lista de denegación del administrador de tu equipo se rechazan con un mensaje de política antes de ejecutarse, incluso en flujos que omiten las solicitudes de aprobación.

1.0.26

  • Precalienta un espacio de trabajo local antes del primer envío. platform.prewarmLocalWorkspace(options) resuelve de antemano las reglas, skills, servidores MCP y archivos ignorados, para que el primer send() en ese espacio de trabajo empiece de inmediato. Devuelve una función de liberación a la que debes llamar al apagar.
  • Controla cuánto tiempo permanecen en caché los escaneos del espacio de trabajo. configureCursorSdk({ local: { workspaceScanCacheTtlMs } }) establece la duración de la caché de los escaneos del espacio de trabajo, y la variable de entorno CURSOR_RIPWALK_CACHE_TTL_MS establece el mismo valor para las implementaciones alojadas. Los servidores de larga duración con checkouts estables ya pueden evitar volver a escanear una y otra vez.
  • Las herramientas personalizadas se ejecutan sin solicitar aprobación. Las herramientas definidas por el host que se pasan mediante customTools ya no fallan con un error de aprobación interactiva en ejecuciones locales en sandbox o con Auto-review. Las reglas de denegación y los límites del sandbox se siguen aplicando.
  • Binarios de macOS firmados. Los paquetes de plataforma macOS de @cursor/sdk ahora incluyen binarios con firma de código, por lo que Gatekeeper y las herramientas de seguridad de endpoints ya no los bloquean.
  • Jerarquía de excepciones de Python más clara. PermissionDeniedError, BadRequestError e InternalServerError ahora heredan directamente de CursorSDKError en lugar de AuthenticationError, ConfigurationError y NetworkError, de modo que los bloques except capturan exactamente lo que indican sus nombres.
  • Corregidos los fallos intermitentes de inicio en Python. Aproximadamente 1 de cada 64 lanzamientos de agentes fallaba antes de llegar al primer envío. Ahora los lanzamientos son fiables.

1.0.25

  • Consumo facturado y coste bajo demanda. agent.getUsage() en TypeScript y agent.get_usage() en Python devuelven el consumo de tokens, el coste facturado y un desglose por ejecución para los agentes en la nube, y Agent.getUsage(agentId) funciona sin necesidad de un identificador. El servidor calcula el coste automáticamente, incluye los descuentos y lo consolida poco después de que termine cada ejecución. Por ahora solo está disponible en Cloud; en las ejecuciones locales se lanza un error de configuración tipado.

1.0.24

  • TypeScript y Python ahora se publican a la vez. A partir de la 1.0.24, @cursor/sdk en npm y cursor-sdk en PyPI se lanzan en la misma versión y comparten número de versión. Las versiones de Python ya no van por detrás de las de TypeScript.
  • Flujos de larga duración más fiables. Las respuestas en streaming de ejecuciones pesadas ya no se cortan a mitad del flujo, algo que antes se manifestaba como errores de red en los clientes de red de Python durante interacciones largas.

1.0.23

Ships with Python SDK 0.1.9.

  • Variables de entorno por envío para ejecuciones en Cloud. Pasa send(prompt, { cloud: { envVars } }) para limitar las variables de entorno a una sola ejecución, incluido el primer envío que crea el agente. Agent.create({ cloud: { envVars } }) sigue estableciendo valores predeterminados con scope del agente.
  • Detalles de error en ejecuciones fallidas. Las ejecuciones locales y en Cloud que fallan ahora exponen un error estructurado con los campos message y code, para que puedas saber qué salió mal sin tener que analizar el registro. run.wait() se comporta igual que antes.
  • Consumo de tokens en Python. Los flujos de ejecución emiten mensajes usage tipados con el recuento de tokens por interacción, y los totales acumulados están disponibles en run.usage y RunResult.usage, igual que en TypeScript desde la 1.0.22.
  • Historial de ejecuciones locales más robusto. El historial de ejecuciones en disco ahora resiste escrituras interrumpidas, lo que soluciona un tipo de fallos en los que un proceso que se cerraba inesperadamente dejaba ejecuciones imposibles de reanudar.
  • Solución a los bloqueos de streaming en Bun. Los flujos de ejecución en Bun ya no se bloquean con respuestas largas.

1.0.22

  • Consumo de tokens en cada ejecución. Las ejecuciones locales emiten eventos usage por interacción en run.stream() y totales acumulados en run.wait(). Las ejecuciones en la nube exponen el mismo consumo en su flujo y en los resultados de wait(), y los totales se conservan en los identificadores locales desconectados, de modo que un proceso que vuelva a conectarse pueda seguir obteniéndolos.

1.0.21

  • Ejecuta agentes en Bun. agent.send() ahora funciona en Bun con el mismo comportamiento que en Node. Esto también corrige un problema en instalaciones nuevas de Node a las que les podía faltar una dependencia necesaria.
  • Nombres de entorno de ejecución más intuitivos en Python. Las APIs de listado y get_run aceptan runtime="cloud", "local" y "auto", conforme a los valores documentados.

1.0.20

  • El SDK se importa sin problemas en Bun. Importar @cursor/sdk ya no provoca un fallo en Bun. La compatibilidad para ejecutar agentes de programación en Bun llegará en la versión 1.0.21.