Sviluppo ottimizzato per gli agenti

Cloud Workstations fornisce un ambiente di runtime ottimizzato per agenti di codifica AI autonomi e interattivi, come Antigravity CLI e Claude Code. Quando esegui workflow di sviluppo agentici, gli agenti eseguono spesso attività asincrone a lunga esecuzione (come la generazione di codice, il refactoring approfondito e l'esecuzione dei test) o si mettono in pausa in attesa dell'input e della revisione da parte dell'utente.

I timeout di inattività standard delle workstation possono arrestare ed eliminare le VM delle 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 salva la RAM, i processi in esecuzione, i file aperti e il contesto dell'agente attivo della macchina virtuale nello spazio di archiviazione permanente, interrompendo al contempo i costi di calcolo di vCPU e memoria.
  2. Hook keep-alive del ciclo di vita: questi hook consentono agli agenti AI di eseguire uno script keep-alive in background (/google/scripts/keep_alive.sh) durante l'elaborazione attiva per evitare timeout e di terminare lo script quando sono in attesa dell'input utente o dopo aver completato le attività, consentendo alla workstation di entrare in uno stato di inattività e di sospendersi.

Come funziona l'ottimizzazione degli agenti

L'ottimizzazione degli agenti garantisce uno stato persistente, l'efficienza dei costi e un funzionamento senza interruzioni durante le attività a lunga esecuzione:

  • 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 segnali keep-alive periodici 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 eseguire una revisione o fornire input aggiuntivi, un hook di evento termina il processo keep-alive in background.
  • Sospensione automatica: senza 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 raggiungimento del timeout, Cloud Workstations imposta la workstation su STATE_SUSPENDED anziché arrestarla.
  • Ripresa immediata: quando lo sviluppatore torna e si riconnette (tramite la Google Cloud console, 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.

Configurare la sospensione della workstation

Per abilitare 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 alla modalità di utilizzo degli esempi in questa pagina:

Console

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

gcloud

Nella Google Cloud console, attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della Google Cloud console, viene avviata una sessiona di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già inclusa e 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 a gcloud CLI con la tua identità federata.

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

Console

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

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

    Vai a Configurazioni workstation

  2. Fai clic su Aggiungi Crea oppure fai clic su una configurazione esistente e poi su Modifica Modifica.

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

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

  5. Nel menu a discesa Azione in caso di inattività, seleziona Sospendi (o Sospendi workstation in caso di 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 gcloud workstations configs create comando con il --idle-action=suspend flag:

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

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

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

Configurare gli agenti con hook keep-alive di esempio

Le immagini di base preconfigurate di Cloud Workstations sono preinstallate con file di configurazione degli agenti di esempio in /google/samples/agents/keepalive/. Questi esempi mostrano come configurare gli agenti di codifica AI per gestire automaticamente il ciclo di vita keep-alive.

Come funzionano gli hook keep-alive degli agenti

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

  • Hook di avvio dell'esecuzione: si attiva prima che l'agente inizi a elaborare l'input dell'utente. L'hook avvia /google/scripts/keep_alive.sh in background e scrive l'ID del processo in background (PID) in un file temporaneo (ad esempio, /tmp/agent_keep_alive.pid).
  • Hook di notifica / attesa dell'input utente: si attiva quando l'agente completa l'attività o si mette in pausa per chiedere all'utente di fornire 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 di 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 input utente. Termina il processo keep-alive attivo in background:

    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

Antigravity CLI supporta gli hook di 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 di attesa.

Riprendere una workstation sospesa

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

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

  • gcloud CLI: esegui il gcloud workstations start comando:

    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 vai all'URL web della workstation o ti connetti tramite SSH, la workstation viene ripresa automaticamente.

Una volta ripresa, 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