· Registro de cambios

Registro de cambios

Almacenes personalizados, herramientas personalizadas y Auto-review para el Cursor SDK

Hemos lanzado un conjunto de nuevas funcionalidades en los SDK de TypeScript y Python. Ahora puedes elegir cómo se almacenan los metadatos del agente y de la ejecución, exponer tus propias funciones al agente como herramientas, dirigir las llamadas locales a herramientas a través de Auto-review y anidar subagentes con cualquier nivel de profundidad. Esta versión también incorpora un conjunto de correcciones de fiabilidad, rendimiento y plataforma que facilitan la ejecución de agentes del SDK locales y en Cloud en scripts de producción, CI e integraciones personalizadas.

Herramientas personalizadas

Ahora puedes proporcionar tus propias herramientas al agente local pasando definiciones de funciones mediante local.customTools, en Agent.create() o en cada send(). El SDK se las expone al agente a través de un servidor MCP integrado llamado custom-user-tools, para que el modelo llame a tu código a través de la misma ruta y el mismo control de permisos que cualquier otra herramienta MCP.

Antes, exponer una capacidad personalizada implicaba configurar tu propio servidor MCP por stdio o HTTP remoto y conectarlo al agente. Ahora basta con una definición de función. Las herramientas personalizadas también son visibles para todos los subagentes de un agente principal, así que una herramienta que defines una vez queda disponible durante toda la ejecución.

Auto-review

Por defecto, un agente local del SDK ejecuta llamadas a herramientas sin pedir aprobación, ya que no hay ningún humano supervisando en una ejecución sin interfaz. Configura local.autoReview para que esas llamadas pasen por Auto-review. Un clasificador decide qué llamadas se ejecutan automáticamente y cuáles se dejan en espera, en lugar de omitir la revisión por completo.

Controlas ese clasificador con instrucciones en lenguaje natural en permissions.json. El campo autoRun.allow_instructions describe patrones de llamadas que conviene permitir, y autoRun.block_instructions describe las que deben dejarse para revisión. Por ejemplo, puedes permitir inspecciones de solo lectura de artefactos de compilación y pausar siempre ante operaciones destructivas, como las eliminaciones.

{
  "autoRun": {
    "allow_instructions": [
      "Read-only inspections of build artifacts under ./dist are fine."
    ],
    "block_instructions": [
      "Always pause delete operations so I get a chance to review them."
    ]
  }
}

JSONL y almacenes personalizados

Ambos SDK conservan los metadatos de agentes y ejecuciones para que puedas reanudar un agente después de reiniciar el proceso. Hasta ahora, ese almacén era SQLite. Ahora también puedes optar por un almacén JSONL, que escribe un archivo de texto sin formato de solo anexado que puedes leer, comparar e incluir en el control de versiones. Tanto SqliteLocalAgentStore como JsonlLocalAgentStore se exportan directamente.

Si ninguna de las opciones predeterminadas se adapta a tu configuración, implementa la interfaz pública LocalAgentStore y pásala a través de local.store. Crea un almacén en memoria para ejecuciones efímeras de CI, o usa Postgres para la persistencia cuando quieras que el estado del agente se almacene junto con el resto de los datos de tu aplicación. El SDK de Python expone almacenes de host, JSONL y JSONL compuestos a través del puente.

Subagentes anidados

Ahora los subagentes pueden crear sus propios subagentes, y así sucesivamente. Un subagente revisor puede delegar en un subagente que escriba pruebas, que a su vez puede seguir delegando, y cada nivel mantiene su propio prompt y modelo. No hace falta activar nada; una sesión de subagente registra el ejecutor que necesita para llamar a Task, por lo que el anidamiento funciona automáticamente para cualquier agente que defina subagentes.

Mejoras de fiabilidad, rendimiento y plataforma

Esta versión también incluye una serie de correcciones de calidad de vida en ambos SDK.

  • Correlación de ejecuciones: Cada send() ahora incluye un requestId generado por la plataforma, expuesto en Run y RunResult y persistido en los almacenes en memoria, SQLite y JSONL. Vincula una ejecución de script o CI con los logs del backend, las analíticas y los hilos de soporte sin tener que inferirlo a partir de agentId.
  • wait() fiable en ejecuciones locales: Las ejecuciones locales ya no resuelven wait() antes de que se escriba el resultado del terminal. La hidratación sigue actualizándose hasta que la ejecución alcanza un estado final, para que la automatización lea un resultado completo.
  • Checkpoints seguros al liberar recursos: Liberar un agente local ya no elimina los datos de checkpoint cuando falta una referencia raíz pero todavía existen blobs de checkpoint. El directorio del agente solo se borra cuando de verdad no queda nada que conservar.
  • Streaming de Cloud sobre HTTP/1.1: Las sesiones de agentes en Cloud ahora se transmiten correctamente en transportes HTTP/1.1 usados por algunos proxies, implementaciones antiguas de fetch en Node y ciertas imágenes de CI. El comportamiento en HTTP/2 no cambia.

  • Importación más ligera: Importar @cursor/sdk ya no carga de forma anticipada toda la pila local de agentes. Los consumidores que solo usan Cloud o solo tipos evitan el coste del runtime local hasta la primera llamada local, sin cambios en la API. La primera llamada local sí asume ese coste de importación una sola vez y luego queda en caché.
  • Tipos de TypeScript autocontenidos: Los archivos .d.ts publicados ya no hacen referencia a paquetes del workspace no publicados. Esto soluciona los errores TS2305 y TS2307 con skipLibCheck: false y los any silenciosos en tipos de stream como TurnEndedUpdate.
  • ripgrep incluido: Las ejecuciones locales de shell usan el binario rg incluido para la plataforma sin modificar tu PATH global. En Windows, anteponer ripgrep ya no sobrescribe la variable Path.

  • Composer 2 se redirige a Composer 2.5: Los clientes del SDK que todavía fijan slugs retirados de composer-2 se redirigen automáticamente a Composer 2.5, manteniendo intactas las variantes rápidas, para que los scripts antiguos sigan funcionando.

  • list_runs con ámbito de workspace: Client, AsyncClient y Agent.list_runs aceptan un cwd opcional, y el puente usa como fallback el workspace desde el que se inició. Esto soluciona resultados espurios de "agent not found" cuando el puente se ejecuta como subproceso.
  • Errores de "no encontrado" más claros: Buscar un agente que no está en el workspace resuelto devuelve un error claro de no encontrado en lugar de un error interno opaco.
  • Versión 0.1.6 y analíticas: cursor-sdk 0.1.6 documenta la ruta de lanzamiento de Buildkite y etiqueta el uso del SDK como sdk-python- para ofrecer analíticas más claras.

Ejecuta npm install @cursor/sdk o pip install cursor-sdk para actualizar. Los scripts que fijan composer-2 pasan a Composer 2.5 automáticamente, y requestId es una incorporación segura al esquema de metadatos de tus ejecuciones. Consulta la documentación de TypeScript y Python para ver todos los detalles.