代理最佳化開發

Cloud Workstations 提供最佳化執行階段環境，適用於自主式和互動式 AI 程式碼編寫代理程式，例如 Antigravity CLI 和 Claude Code。執行代理式開發工作流程時，代理程式經常會執行長時間執行的非同步工作 (例如程式碼生成、深度重構和測試執行)，或在等待人工輸入和審查時暫停。

標準工作站閒置逾時設定可能會在長時間閒置期間關閉並刪除暫時性工作站 VM，導致容器終止，且需要重新初始化代理程式環境。專為代理最佳化的開發 結合兩項主要功能，解決上述問題：

  1. 工作站暫停 (IdleAction.SUSPEND)：這項功能會在工作站 VM 達到閒置逾時時自動暫停，而不是停止。暫停工作站會將虛擬機器的 RAM、執行中的程序、開啟的檔案和作用中的代理程式環境儲存到永久儲存空間，同時停止 vCPU 和記憶體運算費用。
  2. Lifecycle keep-alive hooks：這些掛鉤可讓 AI 代理程式在處理程序啟動期間執行背景 keep-alive 指令碼 (/google/scripts/keep_alive.sh)，防止逾時，並在等待使用者輸入內容或完成工作後終止指令碼，讓工作站進入閒置狀態並暫停。

代理最佳化功能的運作方式

代理程式最佳化可確保長期工作期間的持續狀態、成本效益和無縫運作：

  • 處理中：當代理開始執行使用者指令時，生命週期掛鉤會在背景啟動 /google/scripts/keep_alive.sh。這項指令碼會定期傳送 keep-alive 信號，避免 Cloud Workstations 將工作站標示為閒置。
  • 等待使用者輸入內容或工作完成：當代理程式完成工作或暫停，提示開發人員進行審查或提供額外輸入內容時，事件掛鉤會終止背景的 keep-alive 程序。
  • 自動暫停：如果沒有有效的 keep-alive 信號或傳入流量，工作站的閒置計時器會倒數計時，直到達到設定的閒置逾時門檻為止。逾時後，Cloud Workstations 會將工作站轉換為 STATE_SUSPENDED，而不是關閉。
  • 即時恢復：開發人員返回並重新連線 (透過 Google Cloud 控制台、IDE 或 SSH) 時，工作站會立即從永久儲存空間恢復，完整保留代理程式狀態、終端機工作階段和工作區環境。

設定工作站暫停功能

如要啟用工作站暫停功能，請更新工作站設定，將 idleAction 設為 SUSPEND，並以秒為單位設定 idleTimeout 持續時間，例如 1800s 代表 30 分鐘。

選取這個頁面上您打算如何使用範例的分頁：

控制台

使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，無須設定驗證。

gcloud

在 Google Cloud 控制台中啟用 Cloud Shell。

啟用 Cloud Shell

控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。 Google Cloud Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

    安裝 Google Cloud CLI。

    若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

控制台

如要在Google Cloud 控制台設定工作站設定的暫停功能，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，前往「工作站設定」。

    前往工作站設定頁面

  2. 按一下「新增」 「建立」，或按一下現有設定，然後按一下「編輯」 「編輯」。

  3. 填寫「基本資訊」部分，然後前往「機器設定」。

  4. 在「閒置逾時」下方，設定閒置逾時時間長度，例如 30 分鐘。

  5. 在「閒置動作」下拉式選單中，選取「暫停」 (或「在閒置逾時時暫停工作站」)。

  6. 完成其餘設定步驟，然後按一下「建立」 (或「儲存」)。

gcloud

如要建立啟用暫停功能的新工作站設定，請執行 gcloud workstations configs create 指令並加上 --idle-action=suspend 旗標：

gcloud workstations configs create CONFIG_NAME \
  --cluster=CLUSTER_NAME \
  --region=LOCATION \
  --idle-timeout=1800 \
  --idle-action=suspend

如要更新現有工作站設定以使用暫停功能，請執行 gcloud workstations configs update 指令：

gcloud workstations configs update CONFIG_NAME \
  --cluster=CLUSTER_NAME \
  --region=LOCATION \
  --idle-timeout=1800 \
  --idle-action=suspend

更改下列內容：

  • CONFIG_NAME：工作站設定的名稱。
  • CLUSTER_NAME：工作站叢集的名稱。
  • LOCATION：工作站叢集所在的區域。

REST

如要使用 REST API 設定暫停，請在 workstationConfigs 酬載中，將 idleAction 設為 SUSPEND，並將 idleTimeout 設為所選時間長度：

{
  "idleTimeout": "1800s",
  "idleAction": "SUSPEND"
}

使用範例 keep-alive 掛鉤設定代理程式

Cloud Workstations 預先設定的基本映像檔已預先安裝範例代理程式設定檔，位於 /google/samples/agents/keepalive/ 下方。這些範例示範如何設定 AI 程式碼代理程式，自動管理 keep-alive 生命週期。

代理程式 Keep-Alive Hook 的運作方式

新式 AI 程式碼代理提供事件掛鉤系統，可在重要生命週期里程碑執行指令：

  • 執行開始掛鉤：在代理程式開始處理使用者輸入內容前觸發。這個掛鉤會在背景啟動 /google/scripts/keep_alive.sh，並將背景程序 ID (PID) 寫入暫時檔案 (例如 /tmp/agent_keep_alive.pid)。
  • 通知 / 使用者輸入等待掛鉤：代理程式完成工作或暫停，提示使用者輸入內容時觸發。這個掛鉤會從暫存檔案讀取 PID，並終止背景 keep_alive.sh 程序。

設定 Claude Code

Claude Code 支援在設定中設定的生命週期事件掛鉤。Claude Code 的設定檔範例位於：

/google/samples/agents/keepalive/claude/

在 Claude Code 中，下列事件掛鉤會管理 keep-alive 程序：

  1. UserPromptSubmit：使用者提交提示時執行的掛鉤。在背景啟動 Keep-Alive 指令碼：

    /google/scripts/keep_alive.sh & echo $! > /tmp/claude_keep_alive.pid

  2. Notification：當 Claude Code 發出通知或暫停等待使用者輸入內容時，就會執行 Hook。這會終止作用中的 keep-alive 背景程序：

    if [ -f /tmp/claude_keep_alive.pid ]; then
  kill "$(cat /tmp/claude_keep_alive.pid)" 2>/dev/null || true
  rm -f /tmp/claude_keep_alive.pid
fi

如要套用範例設定，請從 /google/samples/agents/keepalive/claude/ 複製或合併範例檔案至 Claude 設定目錄 (例如 ~/.claude/settings.json 或專案層級設定)。

Antigravity CLI 設定

Antigravity CLI 支援在設定中定義的生命週期事件掛鉤。 Antigravity CLI 的設定檔範例位於：

/google/samples/agents/keepalive/gemini/

在 Antigravity CLI 中，下列事件掛鉤會管理 keep-alive 程序：

  1. BeforeAgent：這個 Hook 會在 Antigravity CLI 開始執行動作前執行。這會在背景啟動保持運作指令碼：

    /google/scripts/keep_alive.sh & echo $! > /tmp/gemini_keep_alive.pid

  2. Notification：當代理完成回合或需要使用者意見回饋時，就會執行掛鉤。終止 keep-alive 程序：

    if [ -f /tmp/gemini_keep_alive.pid ]; then
  kill "$(cat /tmp/gemini_keep_alive.pid)" 2>/dev/null || true
  rm -f /tmp/gemini_keep_alive.pid
fi

如要套用範例設定，請將 /google/samples/agents/keepalive/gemini/ 中的範例檔案複製或合併到 Antigravity CLI 設定目錄 (例如 ~/.gemini/config.yaml 或專案設定)。

整合自訂代理

如果您建構或使用自訂 AI 代理，可以在代理執行期間啟動 /google/scripts/keep_alive.sh 做為背景程序，並在代理進入閒置或等待狀態時終止程序，藉此實作相同的保持連線模式。

恢復遭停權的工作站

工作站處於 STATE_SUSPENDED 狀態時，您可以隨時恢復工作站：

  • Google Cloud 控制台：在 Google Cloud 控制台前往「工作站」頁面，然後點選已暫停工作站旁的「啟動」或「開始」。

  • gcloud CLI：執行 gcloud workstations start 指令：

    gcloud workstations start WORKSTATION_NAME \
  --cluster=CLUSTER_NAME \
  --region=LOCATION \
  --config=CONFIG_NAME

    更改下列內容：

    • WORKSTATION_NAME：工作站名稱。
    • CLUSTER_NAME：工作站叢集的名稱。
    • LOCATION：工作站叢集所在的區域。
    • CONFIG_NAME：工作站設定的名稱。

  • 瀏覽器或 SSH 連線：前往工作站的網頁網址或使用 SSH 連線，都會自動觸發工作站繼續執行。

恢復後，所有終端緩衝區、代理程式指令記錄和工作區檔案都會還原到您離開時的狀態。

後續步驟