Usa la CLI de Antigravity

Usa la CLI de Antigravity

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En esta página, se describe cómo usar la interfaz de línea de comandos (CLI) de Antigravity con una instancia de Gemini Enterprise Agent Platform Workbench.

Este documento está dirigido a analistas de datos, científicos de datos y desarrolladores de datos que trabajan con Agent Platform Workbench. En este documento, se supone que tienes conocimientos sobre cómo escribir código en un entorno de notebook.

Descripción general

La CLI de Antigravity es la interfaz centrada en la terminal de Google Antigravity, un agente de programación con IA que se ejecuta en una terminal. Para obtener más información, consulta antigravity.google.

La CLI de Antigravity está disponible en una terminal en la interfaz de JupyterLab de tu instancia de Agent Platform Workbench. Puedes usarlo para trabajar con los notebooks y archivos de tu instancia, y para ejecutar comandos de shell y comandos de Google Cloud , proporcionando instrucciones en lenguaje natural.

Agent Platform Workbench agrega lo siguiente a la CLI de Antigravity:

• Habilidades de notebooks que crean, explican, editan, verifican y ejecutan notebooks, y crean kernels de Jupyter.
• Un complemento deGoogle Cloud con Google Cloud documentación y orientación para los comandos de gcloud.
• La magia de celda %%agy, que escribe el código para una celda de notebook a partir de tu descripción.

Limitaciones

Ten en cuenta las siguientes limitaciones cuando uses la CLI de Antigravity con Agent Platform Workbench:

• La CLI de Antigravity es solo una CLI. No se incluyen una interfaz de chat gráfica ni herramientas avanzadas en el editor.

• Cuando le pides a la CLI de Antigravity que modifique un notebook, cambia el archivo del notebook directamente en el disco de la instancia. Como resultado, no puedes deshacer las ediciones que realizó la CLI de Antigravity con el botón Deshacer del editor de notebooks o Control+Z (Command+Z en macOS). Sin embargo, puedes pedirle a la CLI de Antigravity que deshaga un cambio con un comando de lenguaje natural, como Undo your last change.

• La CLI de Antigravity escribe directamente en el disco y puede cambiar los archivos que también tienes abiertos en JupyterLab. Si tienes cambios sin guardar en un notebook, guárdalos antes de pedirle a la CLI de Antigravity que modifique ese mismo notebook.

• La CLI de Antigravity está fijada a la versión que se incluye en la imagen de tu instancia y no se puede actualizar por sí sola. Para usar una versión más reciente, actualiza tu instancia a una versión con imágenes más reciente. Para obtener más información, consulta Actualiza el entorno de una instancia.

• La CLI de Antigravity se ejecuta con las credenciales que están activas en tu instancia. De forma predeterminada, estas son las credenciales de la cuenta de servicio de tu instancia de Agent Platform Workbench, por lo que la CLI de Antigravity puede acceder a los mismos recursos que la instancia. Si autenticas una identidad diferente en la instancia (por ejemplo, ejecutando gcloud auth login o gcloud auth application-default login), la CLI de Antigravity usará los permisos de esa identidad.

Antes de comenzar

Como tecnología en etapa inicial, los productos de Gemini para Google Cloud pueden generar resultados que parecen posibles, pero que no son correctos. Te recomendamos que valides todos los resultados de Gemini para los productos de Google Cloud antes de usarlos. Para obtener más información, consulta Gemini para Google Cloud y la IA responsable.

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Roles obligatorios

Para usar la CLI de Antigravity en Agent Platform Workbench, debes otorgar permisos al usuario de la instancia de Agent Platform Workbench y a la cuenta de servicio de la instancia.

Nota: La CLI de Antigravity opera estrictamente dentro de los permisos del entorno de tu instancia de Agent Platform Workbench. Si tú (o la cuenta de servicio que usa tu instancia) no tienen permiso para acceder a un recurso específico, la CLI de Antigravity tampoco podrá acceder a él. Si un comando falla debido a los permisos, pídele a tu administrador que te otorgue los permisos necesarios.

Otorga permisos al usuario de la instancia

Para obtener los permisos que necesitas para usar la CLI de Antigravity en una instancia de Agent Platform Workbench, pídele a tu administrador que te otorgue el rol de IAM de Usuario de Agent Platform (roles/aiplatform.user) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Otorga un permiso a la cuenta de servicio de tu instancia

Para garantizar que la cuenta de servicio de tu instancia de Agent Platform Workbench tenga el permiso necesario para habilitar la ejecución de la CLI de Antigravity en una instancia de Agent Platform Workbench, pídele a tu administrador que otorgue el rol de IAM de usuario de Agent Platform (roles/aiplatform.user) a la cuenta de servicio de tu instancia de Agent Platform Workbench en el proyecto.

Importante: Debes otorgar este rol a la cuenta de servicio de tu instancia de Agent Platform Workbench, no a tu cuenta de usuario. Si no se otorga el rol a la principal correcta, se pueden producir errores de permisos.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso aiplatform.endpoints.predict, que se requiere para habilitar la CLI de Antigravity para que se ejecute en una instancia de Agent Platform Workbench.

Es posible que tu administrador también pueda otorgar este permiso a la cuenta de servicio de tu instancia de Agent Platform Workbench con roles personalizados o con otros roles predefinidos.

Habilita la CLI de Antigravity

La CLI de Antigravity solo está disponible en las instancias de Agent Platform Workbench que usan una imagen de Debian 12 (workbench-instances-2603) o posterior. No se instala en las instancias que usan la imagen de Debian 11 (workbench-instances).

Las instancias nuevas tienen la CLI de Antigravity activada de forma predeterminada. Si no configuras la clave de metadatos de la instancia enable-antigravity cuando creas una instancia, Agent Platform Workbench la establece en true.

Para activar o desactivar la CLI de Antigravity en una instancia, establece la clave de metadatos de la instancia enable-antigravity en false o true y, luego, detén e inicia la instancia. La instancia aplica el parámetro de configuración cuando se inicia. Para obtener más información, consulta Administra funciones a través de metadatos.

Usa la CLI de Antigravity

1. En la consola de Google Cloud , ve a la página Instancias.

   Ir a Instancias

2. Junto al nombre de una instancia de Agent Platform Workbench, haz clic en Abrir JupyterLab.

3. En JupyterLab, haz clic en Archivo > Nuevo selector.

4. En la pestaña Selector, en la sección Otros, haz clic en la tarjeta CLI de Antigravity.

   Se abrirá una terminal y se iniciará la CLI de Antigravity. También puedes ingresar agy en cualquier terminal de JupyterLab.

5. Ingresa una instrucción, como "Crea un notebook nuevo llamado 'test-notebook'". Para obtener más ejemplos, consulta Instrucciones de ejemplo.

6. Cuando la CLI de Antigravity proponga una acción, como editar un archivo o ejecutar un comando de shell, revísala y apruébala o recházala. Para obtener más información, consulta Cómo aprobar acciones de herramientas.

Habilidades de Notebook y el complemento de Google Cloud

Las habilidades son instrucciones y secuencias de comandos que la CLI de Antigravity usa para un tipo de tarea. Cuando la CLI de Antigravity está activada, Agent Platform Workbench le otorga las siguientes habilidades de notebook:

• Notebook targeter: Encuentra el notebook que tienes abierto en JupyterLab para que puedas referirte a él como "este notebook".
• Explicador de notebooks: Resume las celdas de un notebook y sus resultados de texto.
• Modificador de notebooks: Agrega y edita celdas. Solo cambia la celda de destino y mantiene el notebook en el formato que usa JupyterLab.
• Validador de notebooks: Comprueba que un notebook sea válido. Te pregunta antes de reparar un notebook que ya no era válido.
• Creador de notebooks: Crea un notebook con un kernel que esté disponible en la instancia.
• Ejecutor de notebooks: Ejecuta un notebook en los kernels de la instancia y guarda los resultados. Si una celda falla, se indica el nombre de la celda.
• Creador de kernels: Crea un entorno de Python y un kernel de Jupyter con los paquetes que solicites.

La CLI de Antigravity también incluye el complemento google-cloud-developer del mercado de complementos de Antigravity. El complemento proporciona orientación a la CLI de Antigravity para los comandos de gcloud, ayuda con la autenticación, Google Cloud documentación y habilidades para productos como Cloud Logging, Cloud Monitoring y Agent Platform.

La CLI de Antigravity usa una habilidad o el complemento cuando tu instrucción lo requiere. No es necesario que las nombres en tu instrucción.

Ejemplos de instrucciones

Para obtener ideas sobre cómo usar la CLI de Antigravity, consulta las siguientes instrucciones de ejemplo:

• "Explica este cuaderno".

• "Agrega una celda a este notebook que trace la distribución de la columna 'age'".

• "Crea un notebook que cargue bigquery-public-data.ml_datasets.census_adult_income en un DataFrame de Pandas y, luego, ejecútalo".

• "Crea un kernel llamado 'forecast' con pandas y prophet".

• "Verifica que todos los cuadernos de este directorio sean válidos".

• "Consulta la tabla bigquery-public-data.ml_datasets.census_adult_income para encontrar la cantidad de personas con un nivel de ingresos superior a 50,000".

Usa la magia de celda %%agy

Para que la CLI de Antigravity escriba el código de una celda en tu notebook, haz lo siguiente:

1. En la primera línea de una celda nueva de un notebook de Python, ingresa %%agy.
2. En las siguientes líneas de la misma celda, describe el código que deseas.
3. Ejecuta la celda.

La CLI de Antigravity agrega una nueva celda debajo con el código. Revisa el código antes de ejecutarlo.

La magia de celda %%agy está diseñada estrictamente para generar código. A diferencia de la interfaz de la terminal, la magia de celda no puede solicitarte aprobación, por lo que rechaza automáticamente cualquier acción que requiera aprobación, como ejecutar un comando de shell.

La magia de celda %%agy está disponible siempre que la CLI de Antigravity esté habilitada.

Aprobar acciones de la herramienta

De forma predeterminada, la CLI de Antigravity en Agent Platform Workbench te pide aprobación antes de realizar cualquier acción, como editar un archivo, ejecutar un comando de shell o recuperar una URL. Revisa cada acción propuesta antes de aprobarla.

Este valor predeterminado protege contra la inyección de instrucciones. Un notebook, una secuencia de comandos o una página web que lea la CLI de Antigravity podría contener instrucciones ocultas que intenten hacer que el agente ejecute comandos que no tenías previsto, como enviar tus datos a una dirección externa. La CLI de Antigravity se ejecuta con las credenciales de tu instancia, por lo que solicitar aprobación te da la oportunidad de ver y detener una acción de este tipo antes de que se ejecute.

Por este motivo, la opción para omitir las solicitudes de aprobación está inhabilitada para la CLI de Antigravity en las instancias de Agent Platform Workbench.

Controla el acceso a la CLI de Antigravity

Puedes controlar el acceso a la CLI de Antigravity en Agent Platform Workbench con los siguientes métodos:

• Un administrador puede establecer la clave de metadatos de la instancia enable-antigravity en false. La tarjeta de la CLI de Antigravity, las habilidades del notebook, el complemento y la magia de celda %%agy se quitan en el próximo inicio de la instancia. El comando agy permanece instalado. Para evitar las llamadas de modelos, usa los métodos que se indican a continuación.

• Un administrador puede configurar una política de la organización para restringir el uso de modelos específicos a nivel de organización, carpeta o proyecto. Consulta Controla el acceso a los modelos de Model Garden.

• Si no se otorga el permiso aiplatform.endpoints.predict, un administrador puede impedir que algunas identidades usen extremos de modelo para la inferencia.

¿Qué sigue?

• Obtén más información sobre Gemini Enterprise Agent Platform.

• Para aprender a configurar los metadatos de la instancia, consulta Administra funciones a través de metadatos.