Builds de agentes en la nube

Los builds preparan el entorno de tu agente en la nube en segundo plano. Cada agente se inicia desde una máquina preparada previamente, con tus repositorios, herramientas y dependencias listos.

Con los builds, obtienes:

• Inicios más rápidos: La clonación, la instalación y la preparación de dependencias se realizan de antemano, para que los agentes arranquen desde un entorno listo en lugar de esperar en cada inicio.
• Inicios fiables: Los agentes siempre se inician desde el último build exitoso. Una instalación fallida o una configuración incorrecta no sustituye al que funciona.
• Entornos observables: Puedes ver cada build, inspeccionar sus registros y commits, y rastrear qué build utilizó cada agente.

Habilitar Builds en un entorno existente

Los entornos nuevos usan Builds de forma predeterminada. Para activar Builds en un entorno existente:

1. Abra Environments en el Cloud Agents dashboard.
2. Seleccione un entorno y abra la pestaña Builds.
3. Elija una de estas opciones de configuración:
   • Seleccione Run setup agent para que un agente inspeccione su entorno, pruebe un Build y proponga los cambios necesarios.
   • Seleccione Enable Builds para activar Builds y crear uno con la configuración actual.
4. Confirme que el primer Build se complete correctamente antes de usarlo en ejecuciones de agentes.

El agente de configuración comprueba qué comandos deben ejecutarse durante un Build y cuáles deben ejecutarse cuando se inicia un agente. En los entornos gestionados desde el panel de control, propone una configuración actualizada para que la revise y guarde. En los entornos definidos en .cursor/environment.json, puede abrir una pull request con los cambios.

Puede seleccionar Test build en la pestaña Builds para probar la configuración sin activar Builds para todas las ejecuciones de agentes. El agente de configuración no activa Builds por usted. Seleccione Enable Builds cuando esté listo.

Cómo funcionan las Builds

Una Build es una instantánea arrancable de un entorno de agente en la nube preparado. Cursor crea Builds antes de las ejecuciones de agentes y mantiene lista para iniciarse la última que se completó correctamente.

Cada Build sigue este ciclo de vida:

1. Activación: Una Build se inicia según una programación, después de guardar una versión del entorno, mediante una solicitud manual o a petición de un agente.
2. Preparación: Cursor parte de tu imagen base, clona cada repositorio del entorno en su rama predeterminada y ejecuta el comando install hasta completarlo.
3. Instantánea: Cursor guarda el estado del disco de la máquina con la versión del entorno y el SHA de commit exacto de cada repositorio.
4. Activación: Una Build completada correctamente pasa a estar activa.
5. Iniciar agentes: Los nuevos agentes, automatizaciones y revisiones de código se inician desde la Build activa.

Cursor mantiene listas copias precalentadas de las Builds activas. Esto elimina la clonación de repositorios y la instalación de dependencias del proceso de inicio del agente.

Si una nueva Build falla, los agentes siguen usando la última Build completada correctamente. Una actualización de dependencia defectuosa, un comando de instalación defectuoso o un Dockerfile defectuoso no reemplazan el entorno activo.

Qué se ejecuta durante una Build y al iniciar un agente

Usa cada comando de entorno en una fase distinta:

Haz que install sea completo e idempotente. Puede ejecutarse repetidamente, incluso sobre un estado de disco preparado previamente. Comandos como npm install, pnpm install y pip install ya admiten este patrón.

Tus entradas de entorno existentes se siguen aplicando. Las Builds usan instantáneas guardadas, .cursor/environment.json, Dockerfiles, comandos de instalación e inicio, secretos y ajustes de red.

Cómo los Builds gestionan el estado de Git

Un Build registra el commit extraído de cada repositorio al ejecutarse.

• Las ejecuciones de la rama predeterminada parten del commit registrado en el Build activo. Los Builds programados actualizan ese commit en segundo plano. Cuando Actualizar compilación obsoleta está activado y un Build supera tu Umbral de obsolescencia, los agentes obtienen al iniciar el código más reciente de la rama predeterminada. Cuando esta configuración está desactivada, los agentes usan tal cual el commit registrado en el Build. El umbral predeterminado es de 24 horas. Establécelo en 0 para obtener siempre los cambios más recientes.
• Las ejecuciones de rama de funcionalidad parten del disco preparado del Build activo y, a continuación, Cursor extrae la rama solicitada. El código fuente coincide con la rama seleccionada y reutiliza las dependencias del Build.
• Los entornos multirrepositorio registran un commit por repositorio y preparan todo el espacio de trabajo en conjunto.

Si una rama de funcionalidad modifica las dependencias, el agente recibe el contexto de tu entorno y el comando de instalación para actualizar el entorno antes de realizar pruebas.

Cómo funcionan los secretos con Builds

Los Builds pueden acceder a los secretos del equipo y del entorno. Úsalos para registros de paquetes privados, almacenes de artefactos y otras credenciales necesarias para install.

Los secretos de usuario se añaden solo cuando se inicia un agente. No están disponibles durante los Builds ni pasan a formar parte de una instantánea compartida.

Guardar la configuración del entorno o cambiar sus secretos activa un nuevo Build.

Gestionar Builds

Abre la pestaña Builds de un entorno para:

• Ver el tipo, el estado y la hora de inicio de cada Build
• Abrir un Build para consultar sus detalles y registros
• Seleccionar Activar compilación (o Probar compilación cuando los Builds estén desactivados) para ejecutar un Build cuando lo necesites
• Activar un Build en borrador o desactivar un Build
• Cancelar un Build en curso
• Iniciar un agente desde un Build específico
• Configurar Actualizar compilación obsoleta y el Umbral de obsolescencia

Cada ejecución de un agente registra el Build desde el que se inició. Usa esta información de procedencia para comparar el comportamiento del entorno con la configuración exacta y los commits del repositorio incluidos en el Build.

Depurar un Build

Abre un Build fallido para inspeccionar sus eventos y registros. Los agentes de programación seguirán iniciándose desde el Build activo correcto mientras diagnosticas el error.

Para reproducirlo exactamente, inicia un agente de programación desde el Build fallido. El agente de programación abre la máquina en el estado en que falló, donde puede inspeccionar los registros, actualizar el entorno, ejecutar un Build de prueba y verificar el resultado.

También puedes pedir a un agente en la nube que inspeccione y gestione Builds mediante el Cursor Cloud MCP integrado. Por ejemplo:

Inspecciona la última Build fallida de este entorno. Corrige laconfiguración del entorno, ejecuta una Build de prueba y verifícala antes de proponer los comandosfinales para instalar e iniciar.

Referencia sobre el comportamiento de las compilaciones

¿Qué Build usa un agente?

De forma predeterminada, un agente usa el Build activo correcto más reciente de su entorno.

También puedes iniciar un agente desde un Build específico para realizar pruebas o depurar.

¿Qué ocurre antes de la primera Build exitosa?

Los agentes usan el flujo de inicio estándar del entorno hasta que la primera Build se completa correctamente. Una Build fallida no interrumpe los flujos de trabajo de los agentes existentes.

¿Qué tan actualizado está el código fuente?

Las ejecuciones de ramas de funcionalidad cambian a la rama solicitada después de que se inicia la compilación. Las ejecuciones de la rama predeterminada comienzan en el commit registrado por la compilación activa. Si Actualizar compilación obsoleta está activado y la compilación supera tu Umbral de obsolescencia, los agentes de programación obtienen al iniciar el código más reciente de la rama predeterminada.

¿Los Builds sustituyen las instantáneas o los Dockerfiles?

No. Una instantánea guardada o un Dockerfile define la máquina base con la que se crea un Build. Cursor clona después los repositorios, ejecuta install y crea una nueva instantánea arrancable.

¿Las Builds admiten varios repositorios?

Sí. Una Build prepara todos los repositorios del entorno y registra el commit utilizado en cada uno.

¿Las compilaciones tienen un coste adicional?

No. Las compilaciones están incluidas con los agentes en la nube.

Relacionado

• Configuración del entorno en la nube
• Capacidades del agente en la nube
• Ajustes de los agentes en la nube