1. Introduzione
Panoramica
Questo lab mostra come implementare in modo sicuro una chiamata basata sugli eventi di un agente ADK di cui è stato eseguito il deployment su Cloud Run utilizzando i servizi Eventarc e Pub/Sub. Il più delle volte, un agente viene chiamato direttamente da un utente o da un altro agente. Tuttavia, quando un agente viene integrato nei workflow esistenti basati su eventi, effettuare una chiamata diretta richiede modifiche al software esistente. L'attivazione di una chiamata dell'agente in base a un evento consente di incorporare un agente nei flussi di lavoro esistenti senza modificarli.
In questo lab proverai a:
In questo lab creerai un'applicazione con agenti ZooKeeper che ha un agente AI e utilizza un paio di strumenti per fornire informazioni sugli animali dello zoo immaginario.
Eseguirai il deployment dell'applicazione ZooKeeper come servizio su Cloud Run, una piattaforma di computing serverless completamente gestita che esegue container stateless sull'infrastruttura di Google. Poi configurerai un trigger Eventarc che richiamerà l'endpoint del servizio per gestire in modo asincrono i messaggi pubblicati in un argomento Pub/Sub. Ti assicurerai che il deployment segua le best practice, tra cui l'utilizzo di service account IAM designati, la concessione dell'accesso con privilegi minimi e la riduzione al minimo di una potenziale superficie di attacco esponendo l'endpoint dell'applicazione ZooKeeper solo a Eventarc. Lo farai con l'aiuto di Cloud Shell e della console Cloud. Utilizzerai le librerie ADK e Cloud SDK per Python. Per verificare il comportamento, utilizzerai gcloud CLI.
Obiettivi didattici
- Esegui il deployment dell'agente ADK in Google Cloud Run.
- Integra il trigger Eventarc con l'agente ADK in esecuzione su Google Cloud Run.
- Proteggi la tua implementazione e l'integrazione con Eventarc utilizzando il principio del privilegio minimo con l'aiuto di Google Cloud IAM.
- Pubblica ed esegui il pull dei messaggi da e verso Pub/Sub.
- Ridurre al minimo l'esposizione pubblica dell'applicazione di cui è stato eseguito il deployment in Google Cloud Run.
Che cosa ti serve
- Browser web Chrome †
- Un Account Google personale ‡
- Un progetto Google Cloud collegato a un account di fatturazione attivo
Tieni presente che il tuo account deve disporre dell'accesso IAM al progetto che ti consente di eseguire il provisioning delle risorse e configurare l'accesso IAM a queste risorse.
† L'esperienza utente con altri browser potrebbe differire da quella descritta nel lab.
‡ L'utilizzo di un account aziendale o scolastico potrebbe essere limitato nell'esecuzione di alcune operazioni descritte nel lab.
2. Configurazione dell'ambiente
Per garantire un ambiente di sviluppo completamente funzionale per il lab, utilizzerai Google Cloud Shell, in cui sono preinstallati tutti gli strumenti necessari. Segui le istruzioni per configurare l'ambiente.
Crea un Account Google, se non ne hai già uno.
Istruzioni di configurazione
- Utilizza il tuo Account Google per accedere a Google Cloud Console.
- 👉 Apri il selettore di progetti nella barra di navigazione in alto (potrebbe essere visualizzato il messaggio "Seleziona un progetto" o il nome di un progetto esistente) oppure fai clic sul tasto di scelta rapida
Ctrl+Oe scegli un progetto esistente o creane uno nuovo.La creazione di un nuovo progetto richiede alcuni secondi. Attendi che sia pronto e selezionalo utilizzando il selettore di progetti.
- 👉 Fai clic sull'icona Cloud Shell nella parte superiore della console Google Cloud. (contrassegnato dal rettangolo rosso):
Se richiesto, fai clic su **Autorizza** nella finestra di dialogo popup per approvare l'utilizzo delle credenziali del tuo account da parte di Cloud Shell.
- 👉💻 Assicurati che gcloud CLI sia configurata per utilizzare il progetto che hai selezionato (o creato). Esegui questo comando per controllare l'ID progetto configurato:
gcloud config get-value projectYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID]sarà l'ID del progetto che hai selezionato o creato.👉💻 Se vedi un altro valore, esegui il seguente comando per configurare l'ID progetto come ID progetto predefinito per i comandi gcloud CLI:gcloud config set project [YOUR_PROJECT_ID]gcloud config set project lab-project-id-example-123
gcloud projects list \ --format='value(projectId)' \ --sort-by='~createTime'
- 👉💻 Configura la posizione per il provisioning delle risorse e l'ID e il numero del progetto nelle variabili di ambiente:
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 Abilita le API di Google richieste per questo lab.
gcloud services enable \ aiplatform.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ pubsub.googleapis.comOperation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.
3. Esegui il deployment dell'applicazione demo ZooKeeper
I seguenti passaggi eseguono il provisioning e la configurazione delle risorse, incluso il deployment dell'applicazione di AI agentica.
Configurazione delle risorse Pub/Sub
Creerai due argomenti Pub/Sub. Uno verrà utilizzato dal servizio di terze parti per inviare eventi alla tua applicazione di AI generativa. Un altro per l'applicazione per pubblicare i risultati dell'elaborazione degli eventi.
- 👉💻 Crea un argomento Pub/Sub utilizzato per attivare l'applicazione di AI agentica:
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 Crea un argomento Pub/Sub in cui l'applicazione può pubblicare le sue risposte:
gcloud pubsub topics create agent_responses export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)") gcloud pubsub subscriptions create agent_responses \ --topic=agent_responses
Configurazione di service account e criteri IAM a livello di progetto
Creerai due service account per limitare l'ambito di accesso del servizio Cloud Run e del trigger Eventarc al minimo, seguendo il principio del privilegio minimo. Il servizio Cloud Run richiede le autorizzazioni per scrivere log e tracce, per chiamare Gemini LLM su Google Vertex AI e per pubblicare i risultati in un argomento Pub/Sub. L'accesso minimo del trigger Eventarc richiede le autorizzazioni per chiamare il servizio Cloud Run ZooKeeper e accedere a Pub/Sub per leggere gli eventi pubblicati. Queste istruzioni ti guidano per concedere al service account del trigger le autorizzazioni necessarie per rappresentare il servizio di sistema Pub/Sub. Dopo aver creato la risorsa trigger Eventarc, esegui il comando che concede il ruolo roles/run.invoker per consentire al service account del trigger di chiamare il servizio Cloud Run.
- 👉💻 Crea un service account per il servizio Cloud Run:
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Concedi all'account di servizio le autorizzazioni per scrivere log e tracce e utilizzare i modelli Gemini su Vertex AI:
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/logging.logWriter" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/cloudtrace.agent" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/aiplatform.user" \ --condition=None - 👉💻 Concedi all'account di servizio le autorizzazioni per pubblicare messaggi nell'argomento "agent_responses":
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 Crea un service account per il trigger Eventarc:
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Concedi le autorizzazioni all'account di servizio di sistema Pub/Sub per effettuare richieste push autenticate:
gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
Deployment dell'app ZooKeeper in Cloud Run
Scaricherai il codice dell'applicazione demo da GitHub. ed esegui il deployment del codice in Cloud Run.
- 👉💻 Scarica l'applicazione di AI agentica:
mkdir zoo-keeper-lab && cd zoo-keeper-lab git init git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos git config set core.sparseCheckout true echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout git pull origin main --depth 1 cd ai-ml/agent-labs/adk_invoke_with_pubsub/ - 👉💻 Esegui il deployment dell'applicazione di AI agentica in Cloud Run:
gcloud run deploy zookeeper-agent \ --region="${LOCATION}" \ --source="." \ --no-allow-unauthenticated \ --quiet \ --service-account="${ZOOKEEPER_SA}" \ --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"
Configura il trigger Eventarc
Dopo aver preparato tutte le risorse (argomenti Pub/Sub, service account IAM e servizio Cloud Run), è il momento di configurare la risorsa trigger Eventarc. Creerai la risorsa trigger Eventarc e concederai le autorizzazioni per chiamare il servizio Cloud Run al service account del trigger.
- 👉💻 Crea trigger Eventarc:
gcloud eventarc triggers create invoke-agent \ --location="${LOCATION}" \ --destination-run-service="zookeeper-agent" \ --destination-run-path="/zookeeper" \ --destination-run-region="${LOCATION}" \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic="${INVOKE_TOPIC_ID}" \ --service-account="${TRIGGER_SA}" - 👉💻 Concedi le autorizzazioni all'account di servizio del trigger per richiamare il servizio Cloud Run:
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
4. Esamina il funzionamento della soluzione
Ora esamina ciò che hai appena eseguito il deployment. Il seguente diagramma mostra tutte le risorse e la loro interazione. Utilizzerai gcloud CLI per pubblicare un messaggio nell'argomento "invoke_agent". In questo modo viene simulato un evento registrato da un servizio di terze parti nel servizio di messaggistica per richiamare l'applicazione di AI con agenti.
Il deployment è protetto seguendo l'accesso con privilegi minimi. Il servizio Cloud Run applica l'autenticazione (vedi l'argomento --no-allow-unauthenticated nel passaggio 9 della sezione precedente). Solo le identità con i ruoli/run.invoker o autorizzazioni simili possono chiamare il servizio. Questo ruolo viene concesso solo al service account del trigger Eventarc. Analogamente, l'accesso all'argomento "invoke_agent" è ridotto al minimo per impedire la pubblicazione non autorizzata di eventi. È comunque possibile chiamare direttamente l'agente ZooKeeper ignorando la pubblicazione nell'argomento Pub/Sub. Consulta la sezione 6 per scoprire come nascondere l'endpoint dell'applicazione dall'accesso pubblico.
Esegui il workflow
Emulerai un evento esterno pubblicando una domanda in linguaggio naturale in ZooKeeper.
👉💻 Utilizza il seguente comando per pubblicare un messaggio nell'argomento Pub/Sub:
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
In realtà, le informazioni sull'evento avranno probabilmente un formato meno leggibile. Per elaborarlo, un'applicazione di AI agentica avrà bisogno di istruzioni dettagliate sul formato dell'evento, sui dati e su cosa deve fare l'agente con le informazioni sull'evento.
Puoi verificare che l'agente abbia ricevuto l'evento, elabori la richiesta e pubblichi la risposta nell'argomento "agent_responses". Per leggere la risposta, utilizzerai l'abbonamento "agent_responses" (il codelab utilizza lo stesso ID sia per l'argomento sia per l'abbonamento per le risposte).
👉💻 Utilizza il seguente comando per leggere la risposta dell'agente dalla sottoscrizione Pub/Sub:
gcloud pubsub subscriptions pull agent_responses --auto-ack
L'output stamperà una tabella con i metadati del messaggio e il payload contenente la risposta che indica che nello zoo ci sono 33 specie. Il flag --auto-ack conferma automaticamente la ricezione del messaggio dopo che è stato recuperato, quindi non verrà inviato di nuovo.
Come funziona
Visualizza il codice sorgente dell'applicazione di AI agentica aprendo l'editor di Cloud Shell e visualizzando i file nella cartella ~/zoo-keeper-lab. Puoi anche visualizzare il codice sorgente su GitHub.
- Il file main.py implementa un'applicazione web FastAPI di base con un singolo gestore che elabora gli eventi Eventarc.
- Il file processor.py analizza il messaggio dell'evento per recuperare l'ID utente e la richiesta. Quindi, crea una nuova sessione nel runner ADK e chiama l'agente Zookeeper per elaborare la richiesta. La risposta dell'agente viene pubblicata nell'argomento Pub/Sub "agent_responses".
- La sottocartella zookeeper_agent ospita il codice sorgente dell'agente ADK. Puoi eseguire il comando
adk run zookeeper_agentdalla cartella principale dell'applicazione per interagire con l'agente utilizzando la CLI adk.
Come risolvere i problemi
Se uno dei comandi precedenti non va a buon fine, leggi attentamente il messaggio di errore. Se il deployment su Cloud Run non va a buon fine, il primo passo è determinare in quale fase del processo si è verificato l'errore.
- Se l'output del comando "gcloud run deploy…" segnala che la build non è riuscita, visualizza l'URL dei log di build nell'output e aprilo in una finestra separata.
- Se l'output indica "service failed to start" (Impossibile avviare il servizio) o un messaggio simile, significa che il servizio viene implementato, ma l'esecuzione del controllo di integrità non va a buon fine. In questo caso, apri Esplora log o consulta il paragrafo seguente per il comando gcloud CLI. Leggi i log per trovare la causa principale dell'errore.
Cosa succede se hai pubblicato un messaggio su Pub/Sub, ma l'agente non risponde o la risposta sembra strana?
👉💻 Utilizza il seguente comando per leggere i log dell'applicazione pubblicati dall'esecuzione recente:
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
I log monitorano l'esecuzione e segnalano errori come payload del messaggio errato o non analizzabile, risposta non valida del modello Gemini, impostazioni dell'ambiente non valide e altri possibili problemi.
5. Rafforzare la sicurezza del deployment
Il servizio Cloud Run di cui hai eseguito il deployment espone un endpoint pubblico che può essere chiamato da chiunque su internet. Sebbene l'endpoint sia protetto per l'invocazione non autorizzata e convalidi rigorosamente la struttura della richiesta, rimane comunque questo vettore di attacco che consente attacchi di tipo denial of service e denial of wallet. Poiché l'unico percorso di chiamata per il servizio nella progettazione attuale è tramite il trigger Eventarc, il servizio non deve esporre il suo endpoint a internet.
👉💻 Chiudi questo vettore di attacco limitando le chiamate al servizio solo alla raccolta limitata di origini, inclusi i trigger Eventarc:
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
Ora, se provi a chiamare l'URL del servizio dalla tua macchina locale, riceverai l'errore "404 Pagina non trovata".
👉💻 Utilizza curl per inviare una richiesta all'endpoint del servizio:
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
Vedrai un output simile al seguente:
<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>404 Page not found</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Page not found</h1> <h2>The requested URL was not found on this server.</h2> <h2></h2> </body></html>
Dopo questa modifica, non è più possibile richiamare ZooKeeper direttamente chiamando l'endpoint del servizio Cloud Run, a meno che non effettui la chiamata dal VPC nello stesso progetto, dalla rete VPC condivisa a cui è configurata la revisione per inviare il traffico o da un host che fa parte del perimetro dei Controlli di servizio VPC.
6. Riepilogo
Complimenti! Hai configurato correttamente un ambiente per richiamare in modo asincrono l'applicazione di AI agentica attivata da eventi in entrata.
Esegui la pulizia
Tieni presente che il mantenimento delle risorse di cui hai eseguito il provisioning potrebbe comportare addebiti sul tuo account di fatturazione. Se non prevedi di utilizzare questo ambiente per altri esperimenti e per evitare addebiti futuri, ti consigliamo di eliminare le risorse create durante questo codelab.
Esistono due metodi:
Metodo 1: chiusura del progetto
La chiusura (eliminazione) del progetto rilascia tutte le risorse e i dati del progetto e scollega l'account di fatturazione. L'utilizzo di questo metodo impedisce l'imposizione di ulteriori addebiti per le risorse o i dati utilizzati per questo codelab. Utilizza questo comando per arrestare il progetto:
gcloud projects delete $(gcloud config get-value project) --quiet
Metodo 2: eliminazione delle risorse nel progetto
L'eliminazione del servizio Cloud Run protegge da ulteriori addebiti per l'utilizzo della piattaforma serverless. Tieni presente che questo metodo non rimuove completamente tutti i dati generati durante il codelab, come i log di Cloud Build e delle applicazioni, le immagini container e così via. Esegui questo comando per eliminare il servizio:
gcloud run services delete zookeeper-agent --region=${LOCATION}
La definizione del trigger Eventarc e gli argomenti Pub/Sub non comportano costi di gestione (per maggiori dettagli, consulta i prezzi di Eventarc e i prezzi di Pub/Sub).
Scopri di più sulla chiusura del progetto.
Passaggi successivi
- Scopri di più sul codice esaminando la demo su GitHub.
- Esamina l'architettura che orchestra l'accesso a sistemi aziendali disparati
- Scopri come attivare Cloud Run utilizzando i trigger Eventarc
- Scopri di più sull'ADK