智能体优化开发

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

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

  1. 工作站暂停 (IdleAction.SUSPEND)：此功能会在工作站虚拟机达到空闲超时时间时自动暂停，而不是停止。 挂起工作站会将虚拟机的 RAM、正在运行的进程、打开的文件和活跃的代理上下文保存到持久性存储空间，同时停止 vCPU 和内存计算费用。
  2. 生命周期保活钩子：这些钩子允许 AI 智能体在主动处理期间运行后台保活脚本 (/google/scripts/keep_alive.sh) 以防止超时，并在等待用户输入或完成任务后终止脚本，从而使工作站进入空闲状态并暂停。

智能体优化的运作方式

智能体优化可确保在长时间运行的任务期间保持状态、提高成本效益并实现无缝运行：

  • 主动处理：当代理开始执行用户指令时，生命周期钩子会在后台启动 /google/scripts/keep_alive.sh。 此脚本会发送定期保活信号，以防止 Cloud Workstations 将工作站标记为空闲。
  • 等待用户输入或任务完成：当代理完成工作或暂停以提示开发者进行审核或提供其他输入时，事件钩子会终止后台 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 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

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 中，以下事件钩子用于管理保活进程：

  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 中，以下事件钩子用于管理保活进程：

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

恢复后，所有终端缓冲区、代理命令历史记录和工作区文件都会恢复到您上次离开时的状态。

后续步骤