代理最佳化開發

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

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

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

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

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

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

設定工作站暫停功能

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

選取這個頁面上範例的預計用途分頁：

控制台

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

gcloud

安裝 Google Cloud CLI，然後 使用聯合身分登入 gcloud CLI。登入後，執行下列指令來初始化 Google Cloud CLI：

gcloud init

REST

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

    安裝 Google Cloud CLI，然後 使用聯合身分登入 gcloud CLI。

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

控制台

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

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

    前往工作站設定頁面

  2. 按一下「add」(新增) 「Create」(建立)，或按一下現有設定，然後按一下「edit」(編輯) 「Edit」(編輯)。

  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"
}

使用範例存留時間掛鉤設定代理程式

Cloud Workstations 預先設定的基本映像檔，已預先安裝 /google/samples/agents/keepalive/ 下的範例代理程式設定檔。這些範例說明如何設定 AI 程式碼編寫代理程式，自動管理保持連線生命週期。

代理程式保持連線狀態的掛鉤運作方式

新一代 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 中，下列事件掛鉤會管理保持連線程序：

  1. UserPromptSubmit：使用者提交提示時，系統會執行 Hook。這會在背景啟動保持連線指令碼：

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

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

    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：在 Antigravity CLI 開始執行動作前，先執行 Hook。這會在背景啟動保持連線指令碼：

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

  2. Notification：當代理程式完成回合或需要使用者意見回饋時，就會執行 Hook。終止保持連線程序：

    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 連線時，系統會自動觸發工作站繼續執行。

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

後續步驟