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 principal 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 diferida?
En el modelo de compilación heredado y no diferido, Gradle evalúa objetos, 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 anticipada desperdicia tiempo de CPU y memoria en variantes y tareas que no se están ejecutando, y provoca conflictos en el orden de evaluación en secuencias de comandos de compilación complejas.
Al realizar 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 la conexión 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. Si los quitas, el AGP podrá admitir 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 ansiosa y se centraba en las tareas. Les brindaba 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, interrumpía las funciones de rendimiento modernas de Gradle.
La nueva API de Variant (androidComponents {}) es diferida y se centra en los artefactos. Utiliza la API de Property de Gradle de forma exhaustiva y quita por completo todas las referencias a Task y TaskProvider, lo que requiere que interactúes de forma clara con las entradas y salidas (Variant.artifacts) en lugar de con las tareas subyacentes.
Qué se quitará y reemplazará
Se borraron todas las interfaces y clases anteriores que se usaban en el DSL heredado y la antigua API de Variant. Para preparar tus secuencias de comandos de compilación y complementos personalizados, migra de las siguientes APIs y marcas que llegaron al final de su ciclo de vida:
| API o función quitada | Se necesita reemplazo o acción |
|---|---|
Acceso directo a la tarea:
|
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 anticipado:
|
La API de Sources: Conecta el directorio de salida de tu tarea personalizada con variant.sources.java.addGeneratedSourceDirectory(...).
|
Acceso a la ruta de clases o a 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 acceso de clase), usa variant.instrumentation.transformClassesWith(...) con AsmClassVisitorFactory.
|
Mutación de propiedad anticipada:
|
Instancias de `MapProperty` diferidas: Usa variant.buildConfigFields.put(...) y variant.manifestPlaceholders.put(...).
|
Marcas de inhabilitación:
|
No hay reemplazo directo. Quita estos parámetros de gradle.properties, ya que el DSL moderno y Kotlin integrado se aplican de forma estricta.
|
Extensiones de la API de Variant heredada:
|
Se reemplazó con androidComponents.onVariants(). |
Filtrado de variantes (bloque variantFilter) |
Reemplaza con 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 la DSL y la API de Variant de reemplazo (androidComponents {}), usa siempre el artefacto gradle-api cuando desarrolles complementos personalizados de Gradle o lógica de compilación.
Pasos de la migración
Para que la actualización a AGP 10.0 sea fluida y predecible, sigue estas prácticas de migración:
- Ejecuta el Asistente de actualización de AGP: Antes de actualizar directamente a la versión 10.0, ejecuta el Asistente de actualización de 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 basadas en IA (como las habilidades de actualización de AGP disponibles en el repositorio de habilidades de Android) para automatizar y simplificar la migración de la lógica de compilación y los DSL complejos 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 sin advertencias de la versión 9.x y sin depender de
android.newDsl=falseoandroid.builtInKotlin=false, la transición a la versión 10.0 será fluida. - Audita los complementos para 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 dependen de tipos de extensiones heredados provocarán errores 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 reales, y comparaciones paralelas, consulta el repositorio oficial de GitHub de gradle-recipes.
A continuación, se muestra una comparación del antes y el después en la que se explica cómo migrar de la consulta anticipada de variantes heredadas a la configuración diferida de variantes con androidComponents {}:
Antes: API de Variant heredada (se quitó 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 variantes 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 el lanzamiento de AGP 10.0 para comenzar a probar sus comportamientos de compilación y validar la compatibilidad. Cuando 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 los siguientes parámetros estrictos de comportamiento:
# 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 totalmente compatibles con los requisitos estrictos de la API de AGP 10.0.
Rechazo selectivo de subproyectos durante la migración
Si deseas habilitar android.newDsl=true de forma global en todo tu proyecto para probar los comportamientos modernos, pero necesitas más tiempo para migrar subproyectos específicos, puedes inhabilitar selectivamente módulos individuales a partir de AGP 9.4.0-alpha04.
Agrega android.newDsl.optOut a gradle.properties especificando las rutas 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 todo 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 de Kotlin), configura esos módulos a nivel del DSL en lugar de a nivel del proyecto. Configura 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 que necesitas. Si te encuentras con un obstáculo para migrar de las APIs antiguas a la nueva API de Variant, que 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 variantes de AGP 10.0 para ver si ya se conoce el problema que impide la migración y agrega un +1 al problema.
- Informa sobre las APIs faltantes: Si tu caso de uso es único, presenta una nueva solicitud de función con nuestra plantilla específica de la API de Variant 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 del complemento.
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 APIs de Variant son estables y las APIs antiguas dejaron de estar disponibles
Las APIs de Variant 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 Variant ya no están disponibles y requieren habilitación explícita para su uso.
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 el DSL ya no están disponibles y requieren habilitación explícita para su uso.
Aún puedes acceder a las clases internas privadas del AGP
Se puede 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 recomendamos usarlas, ya que pueden cambiar por completo en cualquier momento.