SDK
Registro de cambios del SDK
Las últimas funciones, mejoras y soluciones disponibles en el SDK de Cherri Code, que abarca @cursor/sdk en npm y cursor-sdk en PyPI.
- Sustituye la instrucción de sistema.
systemPromptenAgent.create()reemplaza la instrucción de sistema integrada de Cherri Code para el bucle del agente principal por tu propio texto. Las reglas, las skills y los esquemas de herramientas se siguen cargando, y los subagentes conservan sus propias instrucciones. Solo para agentes locales de TypeScript; vuelve a pasarlo enAgent.resume(), y el acceso se activa por cuenta. - Guía una ejecución mientras está en curso.
run.steer(text)inyecta un mensaje en la interacción en curso y resuelvecomplete_delivered, o bienrevert_to_followupcuando debas enviarlo como un seguimiento normal. Funciona mientras se ejecuta un subagente en primer plano, y ese subagente pasa a segundo plano y continúa. Solo para ejecuciones locales de TypeScript; las ejecuciones en la nube resuelvenrevert_to_followup. - Los subagentes en segundo plano devuelven sus resultados. Cuando el agente ejecuta un subagente en segundo plano, su resultado ahora vuelve al agente padre como una interacción de seguimiento en la misma ejecución, en lugar de descartarse cuando termina la interacción del padre.
run.stream()sigue emitiendo durante esas interacciones yrun.wait()se resuelve después de ellas. Agentes locales, en TypeScript y Python. - Anota las herramientas personalizadas.
annotationsen una entrada delocal.customToolstransmite al modelo las anotaciones de herramientas MCP (title,readOnlyHint,destructiveHint,idempotentHint,openWorldHint). Son solo sugerencias descriptivas; el SDK no las aplica. Solo en TypeScript.
- 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 con errores de autenticación. Las ejecuciones en la nube no se ven afectadas.
- Esquemas de salida en herramientas personalizadas.
outputSchemaen TypeScript youtput_schemaen Python declaran un JSON Schema para el resultado estructurado de una herramienta personalizada, que se anuncia al modelo como el esquema de salida MCP de la herramienta. Los resultados no se validan con él. Solo para agentes locales.
- Lanza el SDK como un solo archivo. En Bun,
@cursor/sdkahora se resuelve como un bundle plano de un solo archivo, así quebun build --compilefunciona sin cambiar ningún import y sin másCannot find module './986.js'.@cursor/sdk/bundledy@cursor/sdk/bundled/sqliteexponen el mismo build como entradas explícitas para otros bundlers de un solo archivo, como esbuild. Solo en TypeScript.
- Restringe el conjunto de herramientas del agente.
toolslimita a una lista de permitidos las herramientas integradas disponibles para el modelo ([]significa solo texto), ydisallowedToolselimina herramientas y conserva las demás. Ambos aceptan nombres públicos como"read"o grupos de funcionalidades como"shell"y"mcp", tanto en TypeScript como en Python (tools,disallowed_tools). Por ahora, solo está disponible para agentes locales y no se conserva al usarresume. - Inicia sesión desde el navegador en TypeScript.
Cherri Code.auth.login()abre el inicio de sesión en el navegador, genera una clave de API y la almacena en~/.cursor/sdk/auth.json;Cherri Code.auth.status()yCherri Code.auth.logout()completan la funcionalidad. Después de iniciar sesión,Agent.create()y las lecturas deCherri Code.*funcionan sinapiKeyniCURSOR_API_KEY. - Consumo y costo de los agentes locales.
agent.getUsage()en TypeScript yagent.get_usage()en Python ahora también funcionan con agentes locales y devuelven un desglose por turno. Pasa elrunIdde un resultado anterior para limitarlo a un solo turno. - Abre PR como la aplicación de GitHub de Cherri Code.
cloud.openAsCursorGithubAppen TypeScript yopen_as_cursor_github_appen Python controlan la autoría de los PR. Las claves de cuentas de servicio usan la aplicación de forma predeterminada; las claves de usuario usan de forma predeterminada al propietario de la clave. - Espacios de trabajo locales con varias raíces. Pasa
local.dirspara cargar reglas, habilidades y contexto del proyecto desde varias carpetas;cwdsigue siendo el único directorio de trabajo principal. Sustituye la forma de matriz decwd, que siempre usaba solo la primera entrada. - Errores de Python más claros. Los fallos que antes aparecían como un simple "error interno" ahora incluyen el mensaje y el código subyacentes.
- Las listas de denegados de comandos de Admin se aplican a ejecuciones locales. Los comandos de shell que coincidan con la lista de denegados de Admin de tu equipo se rechazan con un mensaje de política antes de ejecutarse, incluso en rutas que omiten las solicitudes de aprobación.
- Precalienta un espacio de trabajo local antes del primer envío.
platform.prewarmLocalWorkspace(options)resuelve reglas, skills, servidores MCP y archivos de exclusión de antemano, para que el primersend()a ese espacio de trabajo se inicie de inmediato. Devuelve una función de liberación que debe llamarse al cerrar. - Controla cuánto tiempo se almacenan en caché los análisis del espacio de trabajo.
configureCursorSdk({ local: { workspaceScanCacheTtlMs } })establece la duración de la caché para los análisis del espacio de trabajo, y la variable de entornoCURSOR_RIPWALK_CACHE_TTL_MSestablece el mismo valor para implementaciones alojadas. Los servidores de larga duración con checkouts estables ahora pueden omitir análisis repetidos. - Las herramientas personalizadas se ejecutan sin solicitudes de aprobación. Las herramientas definidas por el host que se pasan mediante
customToolsya no fallan con un error de aprobación interactiva en ejecuciones locales aisladas o de revisión automática. Las reglas de denegación y los límites del sandbox siguen aplicándose. - Binarios de macOS firmados. Los paquetes de plataforma de macOS de
@cursor/sdkahora incluyen binarios firmados, por lo que Gatekeeper y las herramientas de seguridad de endpoints ya no los bloquean. - Jerarquía de excepciones de Python más limpia.
PermissionDeniedError,BadRequestErroreInternalServerErrorahora heredan directamente deCursorSDKErroren lugar deAuthenticationError,ConfigurationErroryNetworkError, por lo que los bloquesexceptcapturan lo que indican sus nombres. - Se corrigieron fallos de inicio intermitentes en Python. Aproximadamente 1 de cada 64 lanzamientos de agentes fallaba antes de llegar al primer envío. Ahora los lanzamientos son fiables.
- Consumo y coste facturados bajo demanda.
agent.getUsage()en TypeScript yagent.get_usage()en Python devuelven el consumo de tokens, el coste facturado y un desglose por ejecución de los agentes en la nube, yAgent.getUsage(agentId)funciona sin identificador. El coste se calcula en el servidor, incluye descuentos y se liquida poco después de finalizar una ejecución. Por ahora, solo disponible en la nube; las ejecuciones locales generan un error de configuración tipado.
- TypeScript y Python ahora se publican juntos. A partir de la versión 1.0.24,
@cursor/sdken npm ycursor-sdken PyPI se publican a partir de la misma versión y comparten un número de versión. Las versiones de Python ya no se retrasan respecto a TypeScript. - Flujos de larga duración más fiables. Las respuestas en streaming en ejecuciones exigentes ya no se interrumpen a mitad del flujo, lo que antes se manifestaba como errores de red en clientes de Python durante interacciones largas.
Ships with Python SDK 0.1.9.
- Variables de entorno por envío para ejecuciones en la nube. 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 específicos del agente. - Detalles de error en ejecuciones fallidas. Las ejecuciones locales y en la nube que fallan ahora muestran un error estructurado con los campos
messageycode, para que puedas saber qué salió mal sin analizar registros.run.wait()se comporta igual que antes. - Consumo de tokens en Python. Los flujos de ejecución emiten mensajes
usagetipados con recuentos de tokens por turno, y los totales acumulados están disponibles enrun.usageyRunResult.usage, como en TypeScript desde la versión 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 el que un proceso bloqueado dejaba ejecuciones que no podían reanudarse.
- Corregidos los bloqueos de streaming en Bun. Los flujos de ejecución en Bun ya no se bloquean con respuestas largas.
- Consumo de tokens en cada ejecución. Las ejecuciones locales emiten eventos de
usagepor turno enrun.stream()y totales acumulados enrun.wait(). Las ejecuciones en la nube muestran el mismo consumo en su flujo y en los resultados dewait(), y los totales se conservan para los handles locales desconectados, de modo que un proceso que se reconecta sigue obteniéndolos.
- Ejecuta agentes de programación con Bun.
agent.send()ahora funciona con Bun igual que con Node. Esto también corrige las instalaciones nuevas de Node a las que les podía faltar una dependencia necesaria. - Nombres de runtime más intuitivos en Python. Las API de listado y
get_runaceptanruntime="cloud","local"y"auto", de acuerdo con los valores documentados.
- El SDK se importa correctamente en Bun. Importar
@cursor/sdkya no provoca fallos en Bun. La ejecución de agentes de programación en Bun llegará en la versión 1.0.21.