Desenvolvimento otimizado para agentes

O Cloud Workstations oferece um ambiente de execução otimizado para agentes de programação de IA autônomos e interativos, como a CLI do Antigravity e o Claude Code. Ao executar fluxos de trabalho de desenvolvimento com agentes, eles costumam realizar tarefas assíncronas de longa duração (como geração de código, refatoração profunda e execução do teste) ou pausar enquanto aguardam a entrada e a revisão humana.

Os tempos limite de inatividade padrão da estação de trabalho podem desligar e excluir VMs de estação de trabalho temporárias durante longos períodos de inatividade, encerrando o contêiner e exigindo que o contexto do agente seja reinicializado. O desenvolvimento otimizado para agentes resolve esse problema combinando dois recursos principais:

  1. Suspensão da estação de trabalho (IdleAction.SUSPEND): esse recurso suspende automaticamente a VM da estação de trabalho quando ela atinge o tempo limite de inatividade, em vez de interrompê-la. A suspensão da estação de trabalho preserva a RAM da máquina virtual, os processos em execução, os arquivos abertos e o contexto do agente ativo no armazenamento persistente, interrompendo os custos de computação de vCPU e memória.
  2. Hooks de manutenção do ciclo de vida: esses hooks permitem que os agentes de IA executem um script de manutenção em segundo plano (/google/scripts/keep_alive.sh) durante o processamento ativo para evitar tempos limite e encerrem o script ao aguardar a entrada do usuário ou após concluir as tarefas, permitindo que a estação de trabalho entre em um estado de inatividade e suspenda.

Como funciona a otimização de agentes

A otimização de agentes garante estado persistente, eficiência de custos e operação contínua durante tarefas de longa duração:

  • Processamento ativo: quando um agente começa a executar instruções do usuário, um hook de ciclo de vida inicia /google/scripts/keep_alive.sh em segundo plano. Esse script envia sinais de atividade periódicos que impedem que o Cloud Workstations marque a estação de trabalho como inativa.
  • Aguardando a entrada do usuário ou a conclusão da tarefa: quando o agente conclui o trabalho ou pausa para solicitar ao desenvolvedor uma revisão ou entrada adicional, um hook de evento encerra o processo de sinal de atividade em segundo plano.
  • Suspensão automática: sem sinais de atividade ativos ou tráfego de entrada, o timer de inatividade da estação de trabalho faz a contagem regressiva até o limite de tempo limite de inatividade configurado. Ao atingir o tempo limite, o Cloud Workstations faz a transição da estação de trabalho para STATE_SUSPENDED em vez de desligar.
  • Retomada instantânea: quando o desenvolvedor retorna e se reconecta (pelo Google Cloud console, um ambiente de desenvolvimento integrado ou SSH), a estação de trabalho é retomada imediatamente do armazenamento persistente com o estado completo do agente, as sessões de terminal e o contexto do espaço de trabalho intactos.

Configurar a suspensão da estação de trabalho

Para ativar a suspensão da estação de trabalho, atualize a configuração dela com um idleAction definido como SUSPEND e uma duração idleTimeout em segundos, como 1800s para 30 minutos.

Selecione a guia para como planeja usar as amostras nesta página:

Console

Quando você usa o Google Cloud console para acessar Google Cloud serviços e APIs, não é necessário configurar a autenticação.

gcloud

No Google Cloud console, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do Google Cloud console, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

REST

Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

    Instale a Google Cloud CLI.

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Console

Para configurar a suspensão em uma configuração de estação de trabalho no Google Cloud console:

  1. No Google Cloud console, navegue até Configurações da estação de trabalho.

    Acessar as configurações da estação de trabalho

  2. Clique em add Criar ou em uma configuração atual e clique em edit Editar.

  3. Preencha a seção Informações básicas e acesse Configurações da máquina.

  4. Em Tempo limite de inatividade, defina a duração do tempo limite de inatividade, como 30 minutos.

  5. No menu suspenso Ação de inatividade, selecione Suspender (ou Suspender estação de trabalho no tempo limite de inatividade).

  6. Conclua as etapas de configuração restantes e clique em Criar (ou Salvar).

gcloud

Para criar uma configuração de estação de trabalho com a suspensão ativada, execute o gcloud workstations configs create comando com a --idle-action=suspend flag:

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

Para atualizar uma configuração de estação de trabalho atual para usar a suspensão, execute o gcloud workstations configs update comando:

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

Substitua:

  • CONFIG_NAME: o nome da configuração da estação de trabalho.
  • CLUSTER_NAME: o nome do cluster da estação de trabalho.
  • LOCATION: a região em que o cluster da estação de trabalho está localizado.

REST

Para configurar a suspensão usando a API REST, defina idleAction como SUSPEND e idleTimeout como a duração escolhida no seu workstationConfigs payload:

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

Configurar agentes com hooks de sinal de atividade de amostra

As imagens de base pré-configuradas do Cloud Workstations vêm pré-instaladas com arquivos de configuração de agente de amostra em /google/samples/agents/keepalive/. Essas amostras demonstram como configurar agentes de programação de IA para gerenciar o ciclo de vida do sinal de atividade automaticamente.

Como os hooks de sinal de atividade de agentes funcionam

Os agentes de programação de IA modernos fornecem sistemas de hook de eventos que executam comandos em marcos importantes do ciclo de vida:

  • Hook de início da execução: acionado antes que o agente comece a processar a entrada do usuário. O hook inicia /google/scripts/keep_alive.sh em segundo plano e grava o ID do processo em segundo plano (PID, na sigla em inglês) em um arquivo temporário (por exemplo, /tmp/agent_keep_alive.pid).
  • Hook de notificação / espera de entrada do usuário: acionado quando o agente conclui a tarefa ou pausa para solicitar a entrada do usuário. O hook lê o PID do arquivo temporário e encerra o processo keep_alive.sh em segundo plano.

Configuração do Claude Code

O Claude Code oferece suporte a hooks de eventos de ciclo de vida configurados nas configurações. Os arquivos de configuração de amostra do Claude Code estão localizados em:

/google/samples/agents/keepalive/claude/

No Claude Code, os seguintes hooks de eventos gerenciam o processo de sinal de atividade:

  1. UserPromptSubmit: o hook é executado quando o usuário envia um prompt. Ele inicia o script de sinal de atividade em segundo plano:

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

  2. Notification: o hook é executado quando o Claude Code emite uma notificação ou pausa para a entrada do usuário. Ele encerra o processo de sinal de atividade ativo em segundo plano:

    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

Para aplicar a configuração de amostra, copie ou mescle os arquivos de amostra de /google/samples/agents/keepalive/claude/ no diretório de configuração do Claude (por exemplo, ~/.claude/settings.json ou configuração para envolvidos no projeto).

Configuração da CLI do Antigravity

A CLI do Antigravity oferece suporte a hooks de eventos de ciclo de vida definidos nas configurações. Os arquivos de configuração de amostra da CLI do Antigravity estão localizados em:

/google/samples/agents/keepalive/gemini/

Na CLI do Antigravity, os seguintes hooks de eventos gerenciam o processo de sinal de atividade:

  1. BeforeAgent: o hook é executado antes que a CLI do Antigravity comece a executar ações. Ele inicia o script de sinal de atividade em segundo plano:

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

  2. Notification: o hook é executado quando o agente conclui a vez ou exige feedback do usuário. Ele encerra o processo de sinal de atividade:

    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

Para aplicar a configuração de amostra, copie ou mescle os arquivos de amostra de /google/samples/agents/keepalive/gemini/ no diretório de configuração da CLI do Antigravity (por exemplo, ~/.gemini/config.yaml ou configurações do projeto).

Integração de agente personalizado

Se você criar ou usar agentes de IA personalizados, poderá implementar o mesmo padrão de manutenção iniciando /google/scripts/keep_alive.sh como um processo em segundo plano durante a execução ativa do agente e encerrando o processo quando o agente entrar em um estado de inatividade ou espera.

Retomar uma estação de trabalho suspensa

Quando uma estação de trabalho está em STATE_SUSPENDED, é possível retomá-la a qualquer momento:

  • Google Cloud console: no Google Cloud console, acesse a página Estações de trabalho e clique em Iniciar ou Começar ao lado da estação de trabalho suspensa.

  • gcloud CLI: execute o gcloud workstations start comando:

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

    Substitua:

    • WORKSTATION_NAME: o nome da estação de trabalho.
    • CLUSTER_NAME: o nome do cluster da estação de trabalho.
    • LOCATION: a região em que o cluster da estação de trabalho está localizado.
    • CONFIG_NAME: o nome da configuração da estação de trabalho.

  • Navegador ou conexão SSH: navegar até o URL da Web da estação de trabalho ou se conectar usando SSH aciona automaticamente a retomada da estação de trabalho.

Depois de retomados, todos os buffers de terminal, o histórico de comandos do agente e os arquivos do espaço de trabalho são restaurados exatamente como você os deixou.

A seguir