使用 Antigravity CLI

本页面介绍了如何将 Antigravity 命令行界面 (CLI) 与 Gemini Enterprise Agent Platform Workbench 实例搭配使用。

本文档适用于使用 Agent Platform Workbench 的数据分析师、数据科学家和数据开发者。本文档假定您了解如何在笔记本环境中编写代码。

概览

Antigravity CLI 是 Google Antigravity 的终端优先界面，Google Antigravity 是一个在终端中运行的 AI 编码智能体。如需了解详情，请参阅 antigravity.google。

您可以在 Agent Platform Workbench 实例的 JupyterLab 界面中的终端内使用 Antigravity CLI。您可以使用它来处理实例上的笔记本和文件，并通过自然语言指令运行 shell 命令和 Google Cloud 命令。

Agent Platform Workbench 为 Antigravity CLI 添加了以下内容：

限制

将 Antigravity CLI 与 Agent Platform Workbench 搭配使用时，请考虑以下限制：

  • Antigravity CLI 仅是一个 CLI。不包含图形聊天界面和高级编辑器内工具。

  • 当您要求 Antigravity CLI 修改笔记本时，它会直接在实例的磁盘上更改笔记本文件。因此，您无法使用笔记本编辑器的撤消按钮或 Control+Z（macOS 上为 Command+Z）来撤消 Antigravity CLI 所做的修改。不过，您可以使用自然语言命令（例如 Undo your last change）让 Antigravity CLI 撤消更改。

  • Antigravity CLI 会直接写入磁盘，并且可以更改您在 JupyterLab 中打开的文件。如果笔记本中有未保存的更改，请先保存这些更改，然后再让 Antigravity CLI 修改该笔记本。

  • Antigravity CLI 固定到实例映像中包含的版本，无法自行更新。如需使用较新版本，请将实例升级到较新的映像版本。如需了解详情，请参阅升级实例的环境。

  • Antigravity CLI 使用实例上的有效凭据运行。默认情况下，这些是 Agent Platform Workbench 实例的服务账号凭证，因此 Antigravity CLI 可以访问该实例可以访问的相同资源。如果您在实例上对其他身份进行身份验证（例如，通过运行 gcloud auth login 或 gcloud auth application-default login），则 Antigravity CLI 会改用该身份的权限。

准备工作

  1. 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.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. 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

所需的角色

如需在 Agent Platform Workbench 中使用 Antigravity CLI，您必须向 Agent Platform Workbench 实例的用户和实例的服务账号授予权限。

向实例的用户授予权限

如需获得在 Agent Platform Workbench 实例中使用 Antigravity CLI 所需的权限，请让您的管理员为您授予项目的 Agent Platform User (roles/aiplatform.user) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

向实例的服务账号授予权限

如需确保 Agent Platform Workbench 实例的服务账号拥有必要的权限，以便在 Agent Platform Workbench 实例中运行 Antigravity CLI，请让您的管理员为 Agent Platform Workbench 实例的服务账号授予项目的 Agent Platform User (roles/aiplatform.user) IAM 角色。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含在 Agent Platform Workbench 实例中运行 Antigravity CLI 所需的 aiplatform.endpoints.predict 权限。

您的管理员也可以使用自定义角色或其他预定义角色为 Agent Platform Workbench 实例的服务账号授予此权限。

启用 Antigravity CLI

Antigravity CLI 仅适用于使用 Debian 12 (workbench-instances-2603) 或更高版本映像的 Agent Platform Workbench 实例。它未安装在使用 Debian 11 (workbench-instances) 映像的实例上。

新实例默认会启用 Antigravity CLI。如果您在创建实例时未设置 enable-antigravity 实例元数据键，Agent Platform Workbench 会将其设置为 true。

如需为实例停用或启用 Antigravity CLI，请将 enable-antigravity 实例元数据键设置为 false 或 true，然后停止并启动实例。实例会在启动时应用该设置。如需了解详情，请参阅通过元数据管理功能。

使用 Antigravity CLI

  1. 在 Google Cloud 控制台中，前往实例页面。

    转到“实例”

  2. 在 Agent Platform Workbench 实例名称旁边，点击打开 JupyterLab。

  3. 在 JupyterLab 中，依次点击文件 > 新建启动器。

  4. 在启动器标签页的其他部分中，点击 Antigravity CLI 图块。

    系统会打开一个终端并启动 Antigravity CLI。您也可以在任何 JupyterLab 终端中输入 agy。

  5. 输入提示，例如“创建名为‘test-notebook’的新笔记本”。如需查看更多示例，请参阅提示示例。

  6. 当 Antigravity CLI 建议执行某项操作（例如修改文件或运行 shell 命令）时，请查看并批准或拒绝该操作。如需了解详情，请参阅批准工具操作。

Notebook 技能和 Google Cloud 插件

技能是 Antigravity CLI 用于执行某种任务的指令和脚本。Antigravity CLI 处于开启状态时，Agent Platform Workbench 会为其提供以下笔记本技能：

  • Notebook targeter：查找您在 JupyterLab 中打开的笔记本，以便您可以将其称为“此笔记本”。
  • Notebook explainer：总结笔记本的单元及其文本输出。
  • Notebook 修改者：添加和修改单元。它只会更改目标单元，并使笔记本保持 JupyterLab 使用的格式。
  • 笔记本验证器：检查笔记本是否有效。在修复已无效的笔记本之前，它会先询问您。
  • 笔记本创建者：使用实例上可用的内核创建笔记本。
  • 笔记本执行程序：在实例的内核上运行笔记本并保存输出。如果单元格失败，则会命名该单元格。
  • 内核创建器：使用您请求的软件包创建 Python 环境和 Jupyter 内核。

Antigravity CLI 还附带 Antigravity 插件市场中的 google-cloud-developer 插件。该插件可为 Antigravity CLI 提供 gcloud 命令指导、身份验证帮助、 Google Cloud 文档以及 Cloud Logging、Cloud Monitoring 和 Agent Platform 等产品的技能。

Antigravity CLI 会在您的提示需要时使用技能或插件。您无需在提示中指明其名称。

示例提示

如需了解如何使用 Antigravity CLI，请参阅以下示例提示：

  • “解释此笔记本。”

  • “在此笔记本中添加一个单元，用于绘制‘age’列的分布图。”

  • “创建一个笔记本，将 bigquery-public-data.ml_datasets.census_adult_income 加载到 Pandas DataFrame 中，然后运行该笔记本。”

  • “使用 pandas 和 prophet 创建一个名为‘forecast’的内核。”

  • “请确保此目录中的每个笔记本都是有效的笔记本。”

  • “查询 bigquery-public-data.ml_datasets.census_adult_income 表，找出收入阶层 >50K 的人数。”

使用 %%agy 单元格魔法

如需让 Antigravity CLI 为笔记本中的单元编写代码，请执行以下操作：

  1. 在 Python 笔记本中新单元的第一行，输入 %%agy。
  2. 在同一单元的后续行中，描述您想要的代码。
  3. 运行该单元。

Antigravity CLI 会在下方添加一个包含代码的新单元。请在运行代码前检查代码。

%%agy 单元魔法命令专为生成代码而设计。与终端界面不同，单元魔法无法提示您批准，因此它会自动拒绝任何需要批准的操作，例如运行 shell 命令。

只要启用了 Antigravity CLI，就可以使用 %%agy 单元魔法。

批准工具操作

默认情况下，Agent Platform Workbench 中的 Antigravity CLI 在执行任何操作（例如修改文件、运行 shell 命令或提取网址）之前，都会请求您批准。在批准每项建议的操作之前，请先仔细检查。

此默认设置可防范提示词注入。Antigravity CLI 读取的笔记本、脚本或网页可能包含隐藏指令，这些指令会试图让智能体运行您不希望执行的命令，例如将您的数据发送到外部地址。Antigravity CLI 会使用实例的凭据运行，因此要求审批可让您有机会在操作运行之前查看并阻止该操作。

因此，在 Agent Platform Workbench 实例上，Antigravity CLI 的跳过审批提示选项处于停用状态。

控制对 Antigravity CLI 的访问权限

您可以通过以下方法控制对 Agent Platform Workbench 中的 Antigravity CLI 的访问权限：

  • 管理员可以将 enable-antigravity 实例元数据键设置为 false。然后，在下次启动实例时，Antigravity CLI 块、笔记本技能、插件和 %%agy 单元格魔法都会被移除。agy 命令仍处于安装状态。如需阻止模型调用，请使用以下方法。

  • 管理员可以设置组织政策，以在组织、文件夹或项目级层限制特定模型的使用。请参阅控制对 Model Garden 模型的访问权限。

  • 通过不授予 aiplatform.endpoints.predict 权限，管理员可以阻止某些身份使用模型端点进行推理。

后续步骤