智能体优化开发

Cloud Workstations 为自主型和交互式 AI 编码智能体（例如 Antigravity CLI 和 Claude Code）提供经过优化的运行时环境。 在运行智能体开发工作流时，智能体经常执行长时间运行的异步任务（例如代码生成、深度重构和测试作业），或者在等待人工输入和审核时暂停。

标准工作站闲置超时可能会在长时间不活动期间关闭并删除临时工作站虚拟机，从而终止容器并要求重新初始化智能体上下文。针对智能体优化的开发 通过结合使用以下两项主要功能解决了此问题：

1. 工作站暂停 (IdleAction.SUSPEND) ：此功能会在工作站虚拟机达到闲置超时时自动暂停该虚拟机，而不是停止它。 暂停工作站会将虚拟机的 RAM、正在运行的进程、打开的文件和活跃的智能体上下文保留到永久性存储空间，同时停止 vCPU 和内存计算费用。
2. 生命周期 Keep-Alive 钩子：这些钩子允许 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）时，工作站会立即 从永久性存储空间恢复，并保留完整的智能体状态、终端会话和 工作区上下文。

配置工作站暂停

如需启用工作站暂停，请使用设置为 SUSPEND 的 idleAction 和以秒为单位的 idleTimeout 时长（例如 30 分钟为 1800s）更新工作站配置。

选择标签页以了解您打算如何使用本页面上的示例：

控制台

当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时，无需设置身份验证。

gcloud

在 Google Cloud 控制台中，激活 Cloud Shell。

激活 Cloud Shell

Cloud Shell 会话随即会在控制台的底部启动，并显示命令行提示符。 Google Cloud Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境 。该会话可能需要几秒钟时间来完成初始化。

REST

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的 凭证。

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先 使用联合身份登录 gcloud CLI。

如需了解详情，请参阅 身份验证文档中的使用 REST 时进行身份验证 。 Google Cloud

控制台

如需在 Google Cloud 控制台中配置工作站配置的暂停，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 工作站配置。

   前往工作站配置

2. 点击 add 创建，或点击现有配置，然后点击 edit 修改。

3. 填写基本信息 部分，然后前往机器设置 。

4. 在闲置超时下，设置闲置超时 时长，例如 30 分钟。

5. 在闲置操作 下拉菜单中，选择暂停 （或在闲置超时时暂停工作站 ）。

6. 完成其余配置步骤，然后点击创建 （或保存 ）。

gcloud

如需创建启用暂停的新工作站配置，请运行带有 --idle-action=suspend 标志的 gcloud workstations configs create 命令：

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 配置暂停，请将 idleAction 设置为 SUSPEND，并将 idleTimeout 设置为所选时长，请在您的 workstationConfigs 载荷中：

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

使用示例 Keep-Alive 钩子配置智能体

Cloud Workstations 预配置的基础映像预安装了 /google/samples/agents/keepalive/ 下的示例智能体配置文件。这些示例演示了如何配置 AI 编码智能体以自动管理 Keep-Alive 生命周期。

智能体 Keep-Alive 钩子的工作原理

现代 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 发出通知或暂停以等待用户输入时，钩子会运行。它会终止活跃的 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：在 Antigravity CLI 开始执行操作之前，钩子会运行。它会在后台启动 Keep-Alive 脚本：

   /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 作为后台进程启动，并在智能体进入闲置或等待状态时终止该进程，从而实现相同的 Keep-Alive 模式。

恢复已暂停的工作站

当工作站处于 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 进行连接会自动触发 工作站恢复。

恢复后，所有终端缓冲区、智能体命令历史记录和工作区文件都会完全恢复到您离开时的状态。

后续步骤

• 创建工作站配置。
• 详细了解如何使用 Gemini CLI 进行 AI 智能体辅助编码。
• 探索预配置的基础映像。
• 了解如何使用 SSH 支持进行连接。