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 entrada e revisão humanas.

Os tempos limite de inatividade padrão da estação de trabalho podem desligar e excluir VMs de estação de trabalho efêmeras durante longos períodos de inatividade, encerrando o contêiner e exigindo a reinicialização do contexto do agente. 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 permanente, interrompendo os custos de computação de vCPU e memória.
  2. Hooks de manutenção de atividade do ciclo de vida: esses hooks permitem que os agentes de IA executem um script de manutenção de atividade em segundo plano (/google/scripts/keep_alive.sh) durante o processamento ativo para evitar tempos limite e encerrar 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 inativo e seja suspensa.

Como funciona a otimização de agentes

A otimização do agente garante estado persistente, eficiência de custos e operação perfeita 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 periódicos de atividade 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 gancho de evento encerra o processo de keep-alive em segundo plano.
  • Suspensão automática: sem sinais de atividade ou tráfego de entrada, o timer de inatividade da estação de trabalho faz uma contagem regressiva até o limite de tempo limite de inatividade configurado. Quando o tempo limite expira, 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 console do Google Cloud , um ambiente de desenvolvimento integrado ou SSH), a estação de trabalho é retomada imediatamente do armazenamento permanente 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 de 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 console do Google Cloud para acessar os serviços e as APIs do Google Cloud , não é necessário configurar a autenticação.

gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud 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 nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

    Instale a CLI do Google Cloud.

    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 console doGoogle Cloud :

  1. No console do Google Cloud , acesse Configurações da estação de trabalho.

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

  2. Clique em Adicionar Criar ou em uma configuração atual e em Editar 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 após 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 comando gcloud workstations configs create com a flag --idle-action=suspend:

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 comando gcloud workstations configs update:

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 de 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 payload workstationConfigs:

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

Configurar agentes com ganchos de keep-alive 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/. Esses exemplos demonstram como configurar agentes de programação de IA para gerenciar o ciclo de vida de manutenção ativa automaticamente.

Como os hooks de manutenção de atividade do agente funcionam

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

  • Hook de início da execução: acionado antes de o agente começar a processar a entrada do usuário. O hook inicia /google/scripts/keep_alive.sh em segundo plano e grava o ID de processo em segundo plano (PID) em um arquivo temporário (por exemplo, /tmp/agent_keep_alive.pid).
  • Hook de espera de entrada do usuário / notificação: acionado quando o agente conclui a tarefa ou faz uma pausa para pedir informações ao 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 é compatível com hooks de eventos de ciclo de vida configurados nas definições. Os arquivos de configuração de exemplo para o Claude Code estão localizados em:

/google/samples/agents/keepalive/claude/

No Claude Code, os seguintes hooks de eventos gerenciam o processo de manutenção da conexão:

  1. UserPromptSubmit: o hook é executado quando o usuário envia um comando. Ele inicia o script de manutenção 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 receber uma entrada do usuário. Ele encerra o processo em segundo plano ativo de sinal de atividade:

    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 exemplo, copie ou mescle os arquivos de exemplo 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 é compatível com hooks de eventos de ciclo de vida definidos nas configurações. Os arquivos de configuração de exemplo para a CLI Antigravity estão localizados em:

/google/samples/agents/keepalive/gemini/

Na CLI do Antigravity, os seguintes hooks de eventos gerenciam o processo de manutenção da conexão:

  1. BeforeAgent: o hook é executado antes de a CLI do Antigravity começar a executar ações. Ele inicia o script de manutenção da atividade em segundo plano:

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

  2. Notification: o hook é executado quando o agente conclui o turno 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 exemplo, copie ou mescle os arquivos de exemplo 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 ativa 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 entra em um estado ocioso ou de 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:

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

  • CLI gcloud: execute o comando gcloud workstations start:

    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 de estação de trabalho.
    • LOCATION: a região em que o cluster de estação de trabalho está localizado.
    • CONFIG_NAME: o nome da configuração da estação de trabalho.

  • Conexão por navegador ou 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