使用 Antigravity CLI

本頁面說明如何搭配使用 Antigravity 指令列介面 (CLI) 和 Gemini Enterprise Agent Platform Workbench 執行個體。

本文適用對象為使用 Agent Platform Workbench 的資料分析師、資料科學家和資料開發人員。本文假設您瞭解如何在筆記本環境中編寫程式碼。

總覽

Antigravity CLI 是 Google Antigravity 的終端機優先介面，這是一種在終端機中執行的 AI 程式設計代理。詳情請參閱 antigravity.google。

您可以在 Agent Platform Workbench 執行個體的 JupyterLab 介面中，透過終端機使用 Antigravity CLI。您可以使用自然語言下達指令，處理執行個體上的筆記本和檔案，以及執行殼層指令和 Google Cloud 指令。

Agent Platform Workbench 為 Antigravity CLI 新增下列功能：

限制

搭配使用 Antigravity CLI 與 Agent Platform Workbench 時，請注意下列限制：

  • Antigravity CLI 僅提供 CLI。不含圖形化即時通訊介面和進階編輯器內工具。

  • 當您要求 Antigravity CLI 修改筆記本時，它會直接在執行個體的磁碟上變更筆記本檔案。因此，您無法使用筆記本編輯器的「Undo」(復原) 按鈕或 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. 登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

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

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

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

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

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

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

    8.

必要的角色

如要在 Agent Platform Workbench 中使用 Antigravity CLI，您必須將權限授予 Agent Platform Workbench 執行個體的使用者和執行個體的服務帳戶。

將權限授予執行個體的使用者

如要取得在 Agent Platform Workbench 執行個體使用 Antigravity CLI 所需的權限，請要求管理員授予您專案的Agent Platform 使用者 (roles/aiplatform.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

將權限授予執行個體的服務帳戶

為確保 Agent Platform Workbench 執行個體的服務帳戶具備必要權限，可讓 Antigravity CLI 在 Agent Platform Workbench 執行個體中執行，請要求管理員將專案的 Agent Platform 使用者 (roles/aiplatform.user) IAM 角色授予 Agent Platform Workbench 執行個體的服務帳戶。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 aiplatform.endpoints.predict 權限，可讓 Antigravity CLI 在 Agent Platform Workbench 執行個體中執行。

管理員或許還可透過自訂角色或其他預先定義的角色，將這項權限授予 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 控制台的「Instances」(執行個體) 頁面。

    前往「Instances」(執行個體) 頁面

  2. 按一下 Agent Platform Workbench 執行個體名稱旁的「Open JupyterLab」。

  3. 在 JupyterLab 中，依序點選「File」>「New launcher」。

  4. 在「Launcher」分頁的「Other」部分，點選「Antigravity CLI」圖塊。

    終端機隨即開啟，並啟動 Antigravity CLI。您也可以在任何 JupyterLab 終端機中輸入 agy。

  5. 輸入提示，例如「建立名為『test-notebook』的新筆記本」。如需更多範例，請參閱「提示詞範例」。

  6. Antigravity CLI 建議執行動作時 (例如編輯檔案或執行殼層指令)，請查看並核准或拒絕。詳情請參閱「核准工具動作」。

Notebook 技能和 Google Cloud 外掛程式

技能是 Antigravity CLI 用於某類工作的指令和指令碼。啟用 Antigravity CLI 後，Agent Platform Workbench 會賦予下列筆記本技能：

  • 筆記本指定工具：找出您在 JupyterLab 中開啟的筆記本，以便您將其稱為「這個筆記本」。
  • Notebook 說明工具：總結 Notebook 的儲存格和文字輸出內容。
  • Notebook 修改者：新增及編輯儲存格。只會變更目標儲存格，並保留 JupyterLab 使用的筆記本格式。
  • Notebook 驗證工具：檢查 Notebook 是否有效。如果筆記本已無效，系統會先詢問是否要修復。
  • Notebook creator:建立 Notebook，並使用執行個體上可用的核心。
  • Notebook 執行器：在執行個體的核心上執行 Notebook，並儲存輸出內容。如果儲存格失敗，則會命名該儲存格。
  • 核心建立工具：建立 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 資料表，找出收入級距大於 5 萬的人數。」

使用 %%agy 儲存格魔術指令

如要讓 Antigravity CLI 為筆記本中的儲存格編寫程式碼，請按照下列步驟操作：

  1. 在 Python 筆記本新儲存格的第一行，輸入 %%agy。
  2. 在同一個儲存格的下一行，描述您想要的程式碼。
  3. 執行儲存格。

Antigravity CLI 會在下方新增一個儲存格，並填入程式碼。請先檢查再執行程式碼。

%%agy 儲存格魔術指令僅用於生成程式碼。與終端機介面不同，儲存格魔術指令無法提示您核准，因此會自動拒絕任何需要核准的操作，例如執行殼層指令。

只要啟用 Antigravity CLI，就能使用 %%agy 儲存格魔術指令。

核准工具動作

根據預設，Agent Platform Workbench 中的 Antigravity CLI 會先徵求您的同意，再執行任何動作，例如編輯檔案、執行殼層指令或擷取網址。請先檢查每項提議的操作，再決定是否核准。

這項預設設定可防範提示詞注入。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 權限，就能禁止某些身分使用模型端點進行推論。

後續步驟