El complemento de Android para Gradle (AGP) es el sistema de compilación compatible con aplicaciones para Android. Además, admite la compilación de muchos tipos diferentes de fuentes y su vinculación a una aplicación que puedes ejecutar en un dispositivo Android físico o en un emulador.
En la siguiente sección, se describe la evolución planificada del DSL y la API del AGP. A medida que se incorporen nuevas API en versiones estables, las API anteriores se marcarán como obsoletas. Esas API obsoletas dejarán de estar disponibles en la próxima versión estable. En las siguientes secciones, se proporciona información sobre los próximos cambios en cada versión importante del AGP.
Para obtener un registro más detallado de las bajas o las eliminaciones de la API del AGP, consulta las actualizaciones de la API del AGP.
AGP 10.0 (fines de 2026)
Cambios y modernización de la API del complemento de Android para Gradle 10.0
AGP 10.0 completa la transición a un modelo de compilación completamente diferido y compatible con la caché de configuración. Esta versión es la culminación de un esfuerzo de varios años para reemplazar las APIs heredadas y no diferidas por una arquitectura más segura y con mejor rendimiento.
¿Por qué un modelo de compilación diferido?
En el modelo de compilación heredado y no diferido, Gradle evalúa objetos con rapidez, consulta datos de variantes y configura tareas en todos los módulos del proyecto durante cada sincronización o invocación de compilación. Esta evaluación rápida desperdicia tiempo de CPU y memoria en variantes y tareas que no se están ejecutando, y causa conflictos de ordenamiento de evaluación en secuencias de comandos de compilación complejas.
Cuando se realiza la transición a un modelo de compilación completamente diferido con proveedores diferidos
(Provider<T>) y la API de Variant moderna (androidComponents {}), las propiedades
y el cableado de tareas se calculan de forma diferida a pedido solo cuando el
gráfico de ejecución de compilación activo lo necesita.
Las APIs heredadas que se quitaron en esta versión eran fundamentalmente incompatibles con esta arquitectura moderna. Su eliminación permite que el AGP admita por completo la caché de configuración de Gradle y el aislamiento del proyecto, lo que mejora drásticamente las velocidades de compilación y los tiempos de sincronización en Android Studio.
La diferencia arquitectónica principal
La API de BaseVariant heredada (applicationVariants.all {}) era rápida y centrada en tareas. Les dio a los desarrolladores acceso directo a las tareas de Gradle y a las configuraciones internas durante la fase de configuración, lo que, de forma inherente, interrumpe las funciones de rendimiento modernas de Gradle.
La nueva API de Variant (androidComponents {}) es diferida y centrada en artefactos. Usa la API de Property de Gradle de forma extensiva y quita por completo todas las referencias a
Task y TaskProvider, lo que requiere que interactúes de forma limpia con las entradas y
salidas (Variant.artifacts) en lugar de con las tareas subyacentes.
Qué se quita y se reemplaza
Se borraron todas las interfaces y clases anteriores que se usaban en el DSL heredado y la antigua API de variantes. Para preparar tus secuencias de comandos de compilación y complementos personalizados, migra de las siguientes APIs y marcas de fin de ciclo de vida:
| API o función quitada | Reemplazo o acción necesaria |
|---|---|
Acceso directo a tareas:
|
La API de Artifacts: En lugar de recuperar la tarea para
cambiar su comportamiento, usa variant.artifacts para
agregar, modificar o reemplazar archivos reales (artefactos) que pasan entre
tareas.
|
Registro de fuente rápida:
|
La API de Sources: Conecta el directorio de salida de tu tarea personalizada con variant.sources.java.addGeneratedSourceDirectory(...).
|
Acceso a la ruta de clase o la configuración:
|
La API de Instrumentation: Para modificar o inspeccionar el código de bytes (el caso de uso más común para el acceso a la ruta de clase), usa variant.instrumentation.transformClassesWith(...) con AsmClassVisitorFactory.
|
Mutación de propiedad rápida:
|
Instancias `MapProperty` diferidas: Usa
variant.buildConfigFields.put(...) y
variant.manifestPlaceholders.put(...).
|
Marcas de exclusión:
|
Sin reemplazo directo. Quita estas marcas de
gradle.properties; el DSL moderno y Kotlin integrado se
aplican de forma estricta.
|
Extensiones de la API de Variant heredada:
|
Reemplaza por androidComponents.onVariants(). |
Filtrado de variantes (bloque variantFilter) |
Reemplaza por androidComponents.beforeVariants() usando
selectores de variantes.
|
Componentes del SDK y el NDK:
|
Accede a los componentes del SDK con
androidComponents.sdkComponents.
|
Entornos de prueba:
|
Migra el registro de dispositivos de prueba personalizados a dispositivos administrados por Gradle. |
APIs de registro obsoletas:
|
Se borró sin reemplazo directo. |
| API de Transform |
Reemplaza las transformaciones con la API de Artifacts y
AsmClassVisitorFactory.
|
Para acceder a todas las interfaces y clases de reemplazo del DSL y la API de Variant (androidComponents {})
, usa siempre el gradle-api
artefacto cuando desarrolles complementos de Gradle personalizados o lógica de compilación.
Pasos de la migración
Para que tu actualización a AGP 10.0 sea fluida y predecible, sigue estas prácticas de migración:
- Ejecuta el Asistente de actualización del AGP: Antes de actualizar directamente a la versión 10.0, ejecuta
el Asistente de actualización del AGP oficial en
Android Studio (
Tools > AGP Upgrade Assistant). Automatiza varias migraciones comunes de DSL y secuencias de comandos de compilación, y ayuda a conservar los comportamientos de compilación existentes. - Usa las habilidades del modo de agente en Android Studio: Aprovecha las habilidades de actualización de IA (como las habilidades de actualización del AGP disponibles en el repositorio de habilidades de Android) para automatizar y simplificar la migración de DSLs y lógica de compilación complejas dentro de Android Studio.
- Primero, corrige las advertencias de baja en AGP 9.x: Actualiza tu proyecto a la versión más reciente de AGP 9.x y resuelve todas las advertencias de baja existentes. Una vez que tu proyecto funcione con la versión 9.x sin advertencias y sin depender de
android.newDsl=falseoandroid.builtInKotlin=false, la transición a la versión 10.0 será fluida. - Audita los complementos de Gradle de terceros: Asegúrate de que los complementos de terceros se actualicen a versiones compatibles con AGP 10.0. Los complementos que aún dependan de tipos de extensión heredados causarán fallas de compilación, como
ClassCastException: ... cannot be cast to class BaseExtension. - Usa recetas de migración oficiales: Para obtener ejemplos de migración complejos y del mundo real y comparaciones en paralelo, consulta el repositorio oficial de gradle-recipes en GitHub.
A continuación, se muestra una comparación de antes y después que muestra cómo migrar de la consulta rápida de variantes heredadas a la configuración diferida de variantes con androidComponents {}:
Antes: API de Variant heredada (quitada en AGP 10.0)
// Eager evaluation using the legacy Variant API
android {
applicationVariants.all { variant ->
if (variant.buildType.name == "release") {
// Eagerly queries and modifies properties during evaluation
}
}
}
Después: API de Variant moderna (androidComponents {})
// Lazy, Configuration Cache compatible Variant API
androidComponents {
onVariants(selector().withBuildType("release")) { variant ->
// Safely and lazily configures properties
}
}
Cómo probar el comportamiento de AGP 10.0 en AGP 9.x
No es necesario que esperes la versión de AGP 10.0 para comenzar a probar sus comportamientos de compilación y validar la compatibilidad. Mientras se ejecuta en cualquier versión de AGP 9.x, puedes aplicar de forma explícita el comportamiento de AGP 10.0. Para ello, verifica que tu gradle.properties inhabilite cualquier exclusión y establezca las siguientes marcas de comportamiento estrictas:
# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true
# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true
Si aplicas android.newDsl=true y android.builtInKotlin=true, puedes verificar que tu lógica de compilación personalizada y los complementos de terceros sean completamente compatibles con los requisitos estrictos de la API de AGP 10.0.
Exclusión selectiva de subproyectos durante la migración
Si deseas habilitar android.newDsl=true de forma global en tu proyecto para probar los comportamientos modernos, pero necesitas más tiempo para migrar subproyectos específicos, puedes excluir de forma selectiva módulos individuales a partir de AGP 9.4.0-alpha04.
Agrega android.newDsl.optOut a gradle.properties y especifica las rutas de acceso del proyecto:
# Enable modern DSL globally across the build
android.newDsl=true
# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib
Inhabilitación selectiva de Kotlin integrado por módulo
Si deseas habilitar Kotlin integrado de forma global en tu proyecto (android.builtInKotlin=true), pero necesitas más tiempo para migrar subproyectos específicos de kotlin-android (o para módulos sin código Kotlin), configura esos módulos en el nivel de DSL en lugar del nivel del proyecto. Establece enableKotlin = false dentro del archivo de compilación del módulo:
android {
enableKotlin = false
}
Flujo de trabajo de informes de errores y comentarios
Queremos asegurarnos de que la nueva API de Variant admita los casos de uso requeridos. Si encuentras un obstáculo para migrar de las APIs anteriores en las que la nueva API de Variant no puede adaptarse a tu caso de uso, sigue estos pasos para enviar comentarios:
- Verifica los elementos existentes: Primero, consulta el error de seguimiento global de la API de Variant de AGP 10.0 para ver si ya se conoce el bloqueador de migración y haz clic en +1 en el problema.
- Informa las APIs faltantes: Si tu caso de uso es único, envía una nueva solicitud de función con nuestra plantilla específica de AGP 10.0 para que podamos investigar y ayudarte.
(Tentativo) Se quitó el acceso a las clases internas privadas del AGP
La dependencia del artefacto gradle ahora oculta todas las clases internas
y otorga acceso de compilación solo a las interfaces y clases
disponibles en el artefacto gradle-api. Esto afecta la compilación de complementos.
No es posible agregar una dependencia de forma manual a fin de obtener acceso a las clases internas.
AGP 9.0 (enero de 2026)
Las nuevas API de variantes son estables y las API antiguas dejaron de estar disponibles
Las APIs de variantes que estaban en preparación en 4.1 y 4.2 son
estables y se encuentran en el artefacto gradle-api. Las
interfaces y clases anteriores que se utilizaban en la antigua API de variantes ya no están
disponibles y requieren una aceptación explícita para usarse.
Las nuevas interfaces DSL son estables y las antiguas dejaron de estar disponibles
Las interfaces DSL que estaban en preparación en 4.1, 4.2 y
7.0 ahora son estables y se encuentran en el artefacto gradle-api. Las interfaces y clases anteriores utilizadas en DSL ya no están disponibles y requieren
una aceptación explícita para usarse.
Aún puedes acceder a las clases internas privadas del AGP
Se pueden acceder a las clases internas privadas del AGP, ubicadas en otros artefactos, durante la compilación de archivos de compilación y complementos, pero no te recomendamos usarlas, ya que pueden cambiar por completo en cualquier momento.