Usar a CLI do Antigravity

Usar a CLI do Antigravity

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Nesta página, descrevemos como usar a interface de linha de comando (CLI) do Antigravity com uma instância do Gemini Enterprise Agent Platform Workbench.

Este documento é destinado a analistas de dados, cientistas de dados e desenvolvedores de dados que trabalham com o Workbench da plataforma do agente. Este documento pressupõe que você saiba como escrever código em um ambiente de notebook.

Visão geral

A CLI do Antigravity é a plataforma voltada a terminais do Google Antigravity, um agente de programação de IA que é executado em um terminal. Para mais informações, consulte antigravity.google.

A CLI do Antigravity está disponível em um terminal na interface do JupyterLab da instância do Workbench da plataforma de agentes. Você pode usá-lo para trabalhar com os notebooks e arquivos na sua instância e executar comandos do shell e Google Cloud , fornecendo instruções em linguagem natural.

O Agent Platform Workbench adiciona o seguinte à CLI do Antigravity:

• Habilidades de notebook que criam, explicam, editam, verificam e executam notebooks, além de criar kernels do Jupyter.
• Um plug-in doGoogle Cloud com documentação e orientações do Google Cloud para comandos gcloud.
• O comando mágico de célula %%agy, que escreve o código de uma célula de notebook com base na sua descrição.

Limitações

Considere as seguintes limitações ao usar a CLI do Antigravity com o Agent Platform Workbench:

• A CLI do Antigravity é apenas uma CLI. Uma interface gráfica de chat e ferramentas avançadas no editor não estão incluídas.

• Quando você pede à CLI do Antigravity para modificar um notebook, ela muda o arquivo do notebook diretamente no disco da instância. Por isso, não é possível desfazer as edições feitas pela CLI do Antigravity usando o botão Desfazer do editor de notebooks ou Control+Z (Command+Z no macOS). No entanto, é possível pedir que a CLI do Antigravity desfaça uma mudança usando um comando de linguagem natural, como Undo your last change.

• A CLI do Antigravity grava diretamente no disco e pode alterar arquivos que você também tem abertos no JupyterLab. Se você tiver mudanças não salvas em um notebook, salve-as antes de pedir à CLI do Antigravity para modificar esse mesmo notebook.

• A CLI do Antigravity é fixada na versão incluída na imagem da instância e não pode ser atualizada. Para usar uma versão mais recente, faça upgrade da instância para uma versão de imagem mais recente. Para mais informações, consulte Fazer upgrade do ambiente de uma instância.

• A CLI do Antigravity é executada com as credenciais ativas na sua instância. Por padrão, essas são as credenciais da conta de serviço da instância do Agent Platform Workbench. Assim, a CLI do Antigravity pode acessar os mesmos recursos que a instância. Se você autenticar uma identidade diferente na instância (por exemplo, executando gcloud auth login ou gcloud auth application-default login), a CLI do Antigravity vai usar as permissões dessa identidade.

Antes de começar

Como uma tecnologia em estágio inicial, os produtos do Gemini para Google Cloudpodem gerar uma saída plausível, mas que é factualmente incorreta. Recomendamos que você valide todas as saídas dos produtos do Gemini para Google Cloud antes de usá-las. Para mais informações, consulte Gemini para Google Cloud e IA responsável.

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

Funções exigidas

Para usar a CLI do Antigravity no Agent Platform Workbench, é necessário conceder permissões ao usuário da instância do Agent Platform Workbench e à conta de serviço da instância.

Observação: a CLI do Antigravity opera estritamente dentro das permissões do ambiente da sua instância do Agent Platform Workbench. Se você (ou a conta de serviço usada pela instância) não tiver permissão para acessar um recurso específico, a CLI do Antigravity também não poderá acessá-lo. Se um comando falhar devido a permissões, peça ao administrador para conceder as permissões necessárias.

Conceder permissões ao usuário da instância

Para receber as permissões necessárias para usar a CLI do Antigravity em uma instância do Workbench da Agent Platform, peça ao administrador para conceder a você o papel do IAM de Usuário da Agent Platform (roles/aiplatform.user) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conceder uma permissão à conta de serviço da instância

Para garantir que a conta de serviço da instância do Agent Platform Workbench tenha a permissão necessária para permitir que a CLI do Antigravity seja executada em uma instância do Agent Platform Workbench, peça ao administrador para conceder o papel do IAM de usuário do Agent Platform (roles/aiplatform.user) à conta de serviço da instância do Agent Platform Workbench no projeto.

Importante:conceda esse papel à conta de serviço da instância do Agent Platform Workbench, não à sua conta de usuário. Se o papel não for concedido ao principal correto, poderão ocorrer erros de permissão.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão aiplatform.endpoints.predict, que é necessária para permitir que a CLI do Antigravity seja executada em uma instância do Workbench da plataforma de agentes.

O administrador também pode conceder essa permissão à conta de serviço da instância do Agent Platform Workbench com papéis personalizados ou outros papéis predefinidos.

Ativar a CLI do Antigravity

A CLI do Antigravity está disponível apenas em instâncias do Agent Platform Workbench que usam uma imagem do Debian 12 (workbench-instances-2603) ou mais recente. Ele não é instalado em instâncias que usam a imagem do Debian 11 (workbench-instances).

As novas instâncias têm a CLI do Antigravity ativada por padrão. Se você não definir a chave de metadados da instância enable-antigravity ao criar uma instância, o Agent Platform Workbench vai defini-la como true.

Para ativar ou desativar a CLI do Antigravity em uma instância, defina a chave de metadados da instância enable-antigravity como false ou true e, em seguida, interrompa e inicie a instância. A instância aplica a configuração quando é iniciada. Para mais informações, consulte Gerenciar recursos usando metadados.

Usar a CLI do Antigravity

1. No console do Google Cloud , acesse a página Instâncias.

   Acesse "Instâncias"

2. Ao lado do nome de uma instância do Agent Platform Workbench, clique em Abrir JupyterLab.

3. No JupyterLab, clique em Arquivo > Nova tela de início.

4. Na guia Acesso rápido, na seção Outros, clique no bloco CLI do Antigravity.

   Um terminal é aberto e inicia a CLI do Antigravity. Também é possível inserir agy em qualquer terminal do JupyterLab.

5. Insira um comando, como "Criar um novo notebook chamado 'test-notebook'". Para mais exemplos, consulte Exemplos de comandos.

6. Quando a CLI do Antigravity propõe uma ação, como editar um arquivo ou executar um comando do shell, revise e aprove ou rejeite. Para mais informações, consulte Aprovar ações de ferramentas.

Habilidades do notebook e o Google Cloud plug-in

As habilidades são instruções e scripts que a CLI do Antigravity usa para um tipo de tarefa. Quando a CLI do Antigravity está ativada, o Agent Platform Workbench oferece a ela as seguintes habilidades de notebook:

• Segmentador de notebook: encontra o notebook que você abriu no JupyterLab para que você possa se referir a ele como "este notebook".
• Explicador de notebook: resume as células de um notebook e as saídas de texto delas.
• Modificador de notebook: adiciona e edita células. Ele altera apenas a célula de destino e mantém o notebook no formato usado pelo JupyterLab.
• Validador de notebook: verifica se um notebook é válido. Ele pergunta antes de reparar um notebook que já era inválido.
• Criador de notebooks: cria um notebook com um kernel disponível na instância.
• Executor de notebook: executa um notebook nos kernels da instância e salva as saídas. Se uma célula falhar, ela será nomeada.
• Criador de kernel: cria um ambiente do Python e um kernel do Jupyter com os pacotes que você solicitar.

A CLI do Antigravity também vem com o plug-in google-cloud-developer do marketplace de plug-ins do Antigravity. O plug-in fornece à CLI do Antigravity orientações para comandos gcloud, ajuda com autenticação, documentação do Google Cloud e habilidades para produtos como Cloud Logging, Cloud Monitoring e plataforma de agente.

A CLI do Antigravity usa uma habilidade ou o plug-in quando o comando precisa. Não é necessário nomeá-los no comando.

Comandos de amostra

Para ter ideias de como usar a CLI do Antigravity, confira os seguintes exemplos de comandos:

• "Explique este notebook."

• "Adicione uma célula a este notebook que mostre a distribuição da coluna 'idade'."

• "Crie um notebook que carregue bigquery-public-data.ml_datasets.census_adult_income em um DataFrame do pandas e execute-o."

• "Crie um kernel chamado 'forecast' com pandas e prophet."

• "Verifique se todos os notebooks neste diretório são válidos."

• "Consulte a tabela bigquery-public-data.ml_datasets.census_adult_income para encontrar o número de pessoas com uma faixa de renda superior a 50 mil."

Usar o comando mágico de célula %%agy

Para que a CLI do Antigravity escreva o código de uma célula no notebook, faça o seguinte:

1. Na primeira linha de uma nova célula em um notebook Python, digite %%agy.
2. Nas próximas linhas da mesma célula, descreva o código que você quer.
3. Execute a célula.

A CLI do Antigravity adiciona uma nova célula abaixo com o código. Revise o código antes de executá-lo.

A célula mágica %%agy foi projetada estritamente para gerar código. Ao contrário da interface do terminal, a célula mágica não pode solicitar sua aprovação. Portanto, ela recusa automaticamente qualquer ação que exija aprovação, como executar um comando do shell.

O comando mágico de célula %%agy está disponível sempre que a CLI do Antigravity está ativada.

Aprovar ações de ferramentas

Por padrão, a CLI do Antigravity no Agent Platform Workbench pede sua aprovação antes de realizar qualquer ação, como editar um arquivo, executar um comando shell ou buscar um URL. Analise cada ação proposta antes de aprová-la.

Esse padrão protege contra injeção de comando. Um notebook, script ou página da Web lido pela CLI do Antigravity pode conter instruções ocultas que tentam fazer com que o agente execute comandos não intencionais, como enviar seus dados para um endereço externo. A CLI do Antigravity é executada com as credenciais da sua instância. Portanto, exigir aprovação permite que você veja e interrompa essa ação antes que ela seja executada.

Por esse motivo, a opção de pular as solicitações de aprovação está desativada para a CLI do Antigravity nas instâncias do Agent Platform Workbench.

Controlar o acesso à CLI do Antigravity

É possível controlar o acesso à CLI do Antigravity no Agent Platform Workbench usando os seguintes métodos:

• Um administrador pode definir a chave de metadados da instância enable-antigravity como false. O bloco CLI do Antigravity, as habilidades do notebook, o plug-in e a célula mágica %%agy são removidos na próxima inicialização da instância. O comando agy permanece instalado. Para evitar chamadas de modelo, use os métodos abaixo.

• Um administrador pode configurar uma política da organização para restringir o uso de modelos específicos no nível da organização, da pasta ou do projeto. Consulte Controlar o acesso aos modelos do Model Garden.

• Ao não conceder a permissão aiplatform.endpoints.predict, um administrador pode impedir que algumas identidades usem endpoints de modelo para inferência.

A seguir

• Saiba mais sobre a Gemini Enterprise Agent Platform.

• Para saber como definir metadados de instância, consulte Gerenciar recursos por meio de metadados.