Sviluppo ottimizzato per gli agenti

Cloud Workstations fornisce un ambiente di runtime ottimizzato per agenti di programmazione AI autonomi e interattivi, come Antigravity CLI e Claude Code. Quando vengono eseguiti flussi di lavoro di sviluppo agentici, gli agenti eseguono spesso attività asincrone di lunga durata (come la generazione di codice, il refactoring profondo e l'esecuzione del test) o si mettono in pausa in attesa dell'input e della revisione da parte di un utente.

I timeout di inattività standard della workstation possono arrestare ed eliminare le VM workstation effimere durante lunghi periodi di inattività, terminando il container e richiedendo la reinizializzazione del contesto dell'agente. Lo sviluppo ottimizzato per gli agenti risolve questo problema combinando due funzionalità chiave:

  1. Sospensione della workstation (IdleAction.SUSPEND): questa funzionalità sospende automaticamente la VM della workstation quando raggiunge il timeout di inattività anziché arrestarla. La sospensione della workstation conserva la RAM della macchina virtuale, i processi in esecuzione, i file aperti e il contesto dell'agente attivo nell'archiviazione permanente, interrompendo al contempo i costi di calcolo della vCPU e della memoria.
  2. Hook di keep-alive del ciclo di vita: questi hook consentono agli agenti AI di eseguire uno script di keep-alive in background (/google/scripts/keep_alive.sh) durante l'elaborazione attiva per evitare timeout e terminare lo script quando sono in attesa di input utente o dopo aver completato le attività, consentendo alla workstation di entrare in uno stato di inattività e di sospensione.

Come funziona l'ottimizzazione degli agenti

L'ottimizzazione dell'agente garantisce uno stato persistente, l'efficienza in termini di costi e un funzionamento senza interruzioni durante le attività di lunga durata:

  • Elaborazione attiva: quando un agente inizia a eseguire le istruzioni dell'utente, un hook del ciclo di vita avvia /google/scripts/keep_alive.sh in background. Questo script invia periodicamente segnali di keep-alive che impediscono a Cloud Workstations di contrassegnare la workstation come inattiva.
  • In attesa dell'input utente o del completamento dell'attività: quando l'agente completa il suo lavoro o si mette in pausa per chiedere allo sviluppatore di rivedere o fornire input aggiuntivi, un hook evento termina il processo di keep-alive in background.
  • Sospensione automatica: in assenza di segnali keep-alive attivi o traffico in entrata, il timer di inattività della workstation esegue il conto alla rovescia fino alla soglia di timeout di inattività configurata. Al termine del timeout, Cloud Workstations esegue la transizione della workstation allo stato STATE_SUSPENDED anziché arrestarla.
  • Ripresa istantanea: quando lo sviluppatore torna e si riconnette (tramite la console Google Cloud , un IDE o SSH), la workstation riprende immediatamente dallo spazio di archiviazione permanente con lo stato completo dell'agente, le sessioni del terminale e il contesto dello spazio di lavoro intatti.

Configura la sospensione della workstation

Per attivare la sospensione della workstation, aggiorna la configurazione della workstation con un idleAction impostato su SUSPEND e una durata idleTimeout in secondi, ad esempio 1800s per 30 minuti.

Seleziona la scheda relativa a come prevedi di utilizzare i campioni in questa pagina:

Console

Quando utilizzi la console Google Cloud per accedere ai servizi Google Cloud e alle API, non devi configurare l'autenticazione.

gcloud

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud , viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

REST

Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

    Installa Google Cloud CLI.

    Se utilizzi un provider di identità (IdP) esterno, devi prima accedere alla CLI gcloud con la tua identità federata.

Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Console

Per configurare la sospensione in una configurazione della workstation nella consoleGoogle Cloud :

  1. Nella console Google Cloud , vai a Configurazioni workstation.

    Vai alle configurazioni di workstation

  2. Fai clic su add Crea o fai clic su una configurazione esistente e poi su edit Modifica.

  3. Completa la sezione Informazioni di base e vai a Impostazioni macchina.

  4. In Timeout per inattività, imposta la durata del timeout per inattività, ad esempio 30 minuti.

  5. Nel menu a discesa Azione inattiva, seleziona Sospendi (o Sospendi workstation al timeout di inattività).

  6. Completa i passaggi di configurazione rimanenti e fai clic su Crea (o Salva).

gcloud

Per creare una nuova configurazione della workstation con la sospensione abilitata, esegui il comando gcloud workstations configs create con il flag --idle-action=suspend:

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

Per aggiornare una configurazione della workstation esistente in modo da utilizzare la sospensione, esegui il comando gcloud workstations configs update:

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

Sostituisci quanto segue:

  • CONFIG_NAME: il nome della configurazione della workstation.
  • CLUSTER_NAME: il nome del cluster di workstation.
  • LOCATION: la regione in cui si trova il cluster di workstation.

REST

Per configurare la sospensione utilizzando l'API REST, imposta idleAction su SUSPEND e idleTimeout sulla durata scelta nel payload workstationConfigs:

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

Configura gli agenti con hook keep-alive di esempio

Le immagini di base preconfigurate di Cloud Workstations vengono fornite con file di configurazione dell'agente di esempio preinstallati in /google/samples/agents/keepalive/. Questi esempi mostrano come configurare gli agenti di programmazione AI per gestire automaticamente il ciclo di vita di keep-alive.

Come funzionano gli hook di keep-alive dell'agente

Gli agenti di codifica AI moderni forniscono sistemi di hook per eventi che eseguono comandi in corrispondenza di tappe fondamentali del ciclo di vita:

  • Hook di avvio dell'esecuzione: attivato prima che l'agente inizi a elaborare l'input utente. L'hook avvia /google/scripts/keep_alive.sh in background e scrive l'ID di processo in background (PID) in un file temporaneo (ad esempio, /tmp/agent_keep_alive.pid).
  • Hook di attesa di notifica / input utente: viene attivato quando l'agente completa la sua attività o si mette in pausa per chiedere all'utente di inserire un input. L'hook legge il PID dal file temporaneo e termina il processo keep_alive.sh in background.

Configurazione di Claude Code

Claude Code supporta gli hook degli eventi del ciclo di vita configurati nelle sue impostazioni. I file di configurazione di esempio per Claude Code si trovano in:

/google/samples/agents/keepalive/claude/

In Claude Code, i seguenti hook di eventi gestiscono il processo keep-alive:

  1. UserPromptSubmit: l'hook viene eseguito quando l'utente invia un prompt. Avvia lo script keep-alive in background:

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

  2. Notification: l'hook viene eseguito quando Claude Code emette una notifica o si mette in pausa per l'input utente. Termina il processo in background keep-alive attivo:

    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

Per applicare la configurazione di esempio, copia o unisci i file di esempio da /google/samples/agents/keepalive/claude/ nella directory di configurazione di Claude (ad esempio, ~/.claude/settings.json o la configurazione a livello di progetto).

Configurazione di Antigravity CLI

L'interfaccia a riga di comando Antigravity supporta gli hook degli eventi del ciclo di vita definiti nelle sue impostazioni. I file di configurazione di esempio per Antigravity CLI si trovano in:

/google/samples/agents/keepalive/gemini/

In Antigravity CLI, i seguenti hook di eventi gestiscono il processo keep-alive:

  1. BeforeAgent: l'hook viene eseguito prima che Antigravity CLI inizi a eseguire le azioni. Avvia lo script keep-alive in background:

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

  2. Notification: l'hook viene eseguito quando l'agente completa il suo turno o richiede il feedback dell'utente. Termina il processo 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

Per applicare la configurazione di esempio, copia o unisci i file di esempio da /google/samples/agents/keepalive/gemini/ nella directory di configurazione di Antigravity CLI (ad esempio, ~/.gemini/config.yaml o le impostazioni progetto).

Integrazione di agenti personalizzati

Se crei o utilizzi agenti AI personalizzati, puoi implementare lo stesso pattern keep-alive avviando /google/scripts/keep_alive.sh come processo in background durante l'esecuzione attiva dell'agente e terminando il processo quando l'agente entra in uno stato di inattività o attesa.

Riprendi una workstation sospesa

Quando una workstation è in STATE_SUSPENDED, puoi riprenderla in qualsiasi momento:

  • ConsoleGoogle Cloud : nella console Google Cloud , vai alla pagina Workstation e fai clic su Avvia o Inizia accanto alla workstation sospesa.

  • gcloud CLI: esegui il comando gcloud workstations start:

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

    Sostituisci quanto segue:

    • WORKSTATION_NAME: il nome della workstation.
    • CLUSTER_NAME: il nome del cluster di workstation.
    • LOCATION: la regione in cui si trova il cluster di workstation.
    • CONFIG_NAME: il nome della configurazione della workstation.

  • Connessione tramite browser o SSH: se accedi all'URL web della tua workstation o ti connetti tramite SSH, la workstation riprende automaticamente l'esecuzione.

Una volta ripristinati, tutti i buffer del terminale, la cronologia dei comandi dell'agente e i file dello spazio di lavoro vengono ripristinati esattamente come li avevi lasciati.

Passaggi successivi