Guida rapida: crea ed esegui il deployment di un agente AI in Cloud Run utilizzando l'Agent Development Kit (ADK)

Guida rapida: crea ed esegui il deployment di un agente AI in Cloud Run utilizzando l'Agent Development Kit (ADK)

L'Agent Development Kit (ADK) per Python ti consente di sviluppare agenti AI che utilizzano strumenti personalizzati ed eseguirli come servizi su Cloud Run. In questa guida rapida, esegui il deployment di un agente di esempio che recupera i bollettini meteo per una città.

Quando esegui il deployment dal codice sorgente, Cloud Run crea automaticamente un'immagine container per il tuo servizio. Per ulteriori informazioni su come il buildpack Python determina l'entry point predefinito per i deployment di origine Cloud Run, consulta Creare un'applicazione Python.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

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

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un progetto Google Cloud .

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

• Crea un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Se utilizzi un progetto esistente per questa guida, verifica di disporre delle autorizzazioni necessarie per completare la guida. Se hai creato un nuovo progetto, disponi già delle autorizzazioni necessarie.

Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

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

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un progetto Google Cloud .

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

• Crea un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Se utilizzi un progetto esistente per questa guida, verifica di disporre delle autorizzazioni necessarie per completare la guida. Se hai creato un nuovo progetto, disponi già delle autorizzazioni necessarie.

Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

1. Abilita le API Cloud Run Admin, Vertex AI e Cloud Build, se non sono già abilitate:

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   gcloud services enable run.googleapis.com aiplatform.googleapis.com cloudbuild.googleapis.com

2. Installa l'ADK seguendo le istruzioni riportate nella documentazione dell'Agent Development Kit.

3. Se sei soggetto a un criterio dell'organizzazione con restrizioni di dominio che limitano le chiamate non autenticate per il tuo progetto, devi accedere al servizio di cui è stato eseguito il deployment come descritto in Testare i servizi privati.

4. Esamina i prezzi di Cloud Run o stima i costi con il Calcolatore prezzi.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare questa guida rapida, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Cloud Run Source Developer (roles/run.sourceDeveloper) sul progetto
• Utente Vertex AI (roles/aiplatform.user) sul progetto
• Utente dell'account di servizio (roles/iam.serviceAccountUser) sull'identità di servizio
• Visualizzatore log (roles/logging.viewer) sul progetto

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Concedi al account di servizio Cloud Build l'accesso al tuo progetto

Cloud Build utilizza automaticamente l'account di servizio predefinito di Compute Engine come account di servizio Cloud Build predefinito per creare il codice sorgente e la risorsa Cloud Run, a meno che tu non esegua l'override di questo comportamento.

Affinché Cloud Build possa creare le tue origini, concedi al service account Cloud Build il ruolo Cloud Run Builder (roles/run.builder) nel tuo progetto:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder

Sostituisci PROJECT_ID con l'ID progetto Google Cloude SERVICE_ACCOUNT_EMAIL_ADDRESS con l'indirizzo email del account di servizio Cloud Build. Se utilizzi il account di servizio predefinito di Compute Engine come account di servizio Cloud Build, utilizza il seguente formato per l'indirizzo email del account di servizio:

[e-mail]

Sostituisci PROJECT_NUMBER con il numero del tuo progetto Google Cloud.

Per istruzioni dettagliate su come trovare l'ID progetto e il numero di progetto, vedi Creazione e gestione dei progetti.

La concessione del ruolo di builder Cloud Run richiede un paio di minuti per la propagazione.

scrivi l'applicazione di esempio

Per scrivere un'applicazione in Python:

1. Crea una nuova directory principale denominata parent_folder e passa alla directory:

   mkdir parent_folder
   cd parent_folder
   

2. Nella directory parent_folder, crea una nuova sottodirectory denominata multi_tool_agent e passa a questa directory:

   mkdir multi_tool_agent
   cd multi_tool_agent
   

3. Crea un file __init__.py per importare l'agente:

   from . import agent
   

4. Crea un file agent.py per definire l'agente per rispondere alle domande sull'ora e sul meteo in una città specificata:

   import datetime
   from zoneinfo import ZoneInfo
   from google.adk.agents import Agent
   
   def get_weather(city: str) -> dict:
       """Retrieves the current weather report for a specified city.
   
       Args:
           city (str): The name of the city for which to retrieve the weather report.
   
       Returns:
           dict: status and result or error msg.
       """
       if city.lower() == "new york":
           return {
               "status": "success",
               "report": (
                   "The weather in New York is sunny with a temperature of 25 degrees"
                   " Celsius (77 degrees Fahrenheit)."
               ),
           }
       else:
           return {
               "status": "error",
               "error_message": f"Weather information for '{city}' is not available.",
           }
   
   def get_current_time(city: str) -> dict:
       """Returns the current time in a specified city.
   
       Args:
           city (str): The name of the city for which to retrieve the current time.
   
       Returns:
           dict: status and result or error msg.
       """
   
       if city.lower() == "new york":
           tz_identifier = "America/New_York"
       else:
           return {
               "status": "error",
               "error_message": (
                   f"Sorry, I don't have timezone information for {city}."
               ),
           }
   
       tz = ZoneInfo(tz_identifier)
       now = datetime.datetime.now(tz)
       report = (
           f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
       )
       return {"status": "success", "report": report}
   
   root_agent = Agent(
       name="weather_time_agent",
       model="gemini-2.5-flash",
       description=(
           "Agent to answer questions about the time and weather in a city."
       ),
       instruction=(
           "You are a helpful agent who can answer user questions about the time and weather in a city."
       ),
       tools=[get_weather, get_current_time],
   )
   

5. Crea un file .env e aggiungi le seguenti variabili:

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=PROJECT_ID
   GOOGLE_CLOUD_LOCATION=REGION
   

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID progetto Google Cloud .
   • REGION: la regione in cui prevedi di eseguire il deployment del servizio.

6. Vai alla directory della cartella principale parent_folder e crea un file requirements.txt per aggiungere la dipendenza google-adk:

   google-adk
   

   Il progetto di origine include la seguente struttura:

   parent_folder/
   ├── requirements.txt
   └── multi_tool_agent/
       ├── __init__.py
       ├── agent.py
       └── .env
   

L'app è stata completata ed è pronta per il deployment.

Esegui il deployment in Cloud Run dall'origine

Il deployment dall'origine crea automaticamente un'immagine container dal codice sorgente e ne esegue il deployment.

1. Nella directory del codice sorgente (parent_folder), esegui il deployment su Cloud Run utilizzando il seguente comando:

   gcloud run deploy --source .

   1. Quando ti viene richiesto il nome del servizio, premi Invio per accettare il nome predefinito, ad esempio weather-agent.

   2. Se ti viene chiesto di abilitare API aggiuntive nel progetto, ad esempio l'API Artifact Registry, rispondi premendo y.

   3. Quando ti viene chiesto di selezionare la regione, scegli la regione che preferisci, ad esempio europe-west1.

   4. Se ti viene chiesto di creare un repository nella regione specificata, rispondi premendo y.

   5. Se ti viene chiesto di consentire l'accesso pubblico: rispondi y. Potresti non visualizzare questo prompt se è presente una policy dell'organizzazione con limitazioni del dominio che lo impedisce. Per maggiori dettagli, consulta la sezione Prima di iniziare.

   Poi, attendi qualche istante fino al completamento del deployment. Se l'operazione riesce, la riga di comando visualizza l'URL del servizio dell'agente di cui è stato eseguito il deployment, che avrà il seguente formato: https://weather-agent-123456789101.us-central1.run.app/list-apps.

Esegui l'agente

Per utilizzare l'agente ADK, puoi eseguire i seguenti comandi curl:

1. Per ottenere l'elenco delle app, esegui questo comando:

   curl -X GET SERVICE_URL/list-apps
   

   Sostituisci SERVICE_URL con l'URL del servizio di cui hai eseguito il deployment.

2. Per avviare una sessione, esegui questo comando:

   curl -X POST SERVICE_URL/apps/multi_tool_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": "value2"}'
   

3. Per eseguire una query sull'agente, esegui questo comando:

   curl -X POST SERVICE_URL/run \
   -H "Content-Type: application/json" \
   -d "{\"appName\": \"multi_tool_agent\",\"userId\": \"u_123\",\"sessionId\": \"s_123\",\"newMessage\": { \"role\": \"user\", \"parts\": [{ \"text\": \"What's the weather in New York today?\" }]}}"
   

L'agente restituisce le informazioni meteo nei risultati della query.

Per ulteriori informazioni ed esempi sui comandi curl supportati, consulta Utilizza il server API nella documentazione di ADK.

Operazione riuscita: hai eseguito il deployment di un agente AI utilizzando Agent Development Kit in Cloud Run.

Esegui la pulizia

Per evitare addebiti aggiuntivi al tuo account Google Cloud , elimina tutte le risorse che hai eseguito il deployment con questa guida rapida.

Elimina il repository

Cloud Run non addebita costi quando il servizio di cui è stato eseguito il deployment non è in uso. Tuttavia, ti potrebbero comunque essere addebitati i costi di archiviazione dell'immagine container in Artifact Registry. Per eliminare i repository Artifact Registry, segui i passaggi descritti in Elimina repository nella documentazione di Artifact Registry.

Elimina il servizio

I servizi Cloud Run non comportano costi finché non ricevono richieste. Per eliminare il servizio Cloud Run, segui uno di questi passaggi:

Console

Per eliminare un servizio:

1. Nella console Google Cloud , vai alla pagina Servizi di Cloud Run:

   Vai a Cloud Run

2. Individua il servizio che vuoi eliminare nell'elenco dei servizi e fai clic sulla relativa casella di controllo per selezionarlo.

3. Fai clic su Elimina. Vengono eliminate tutte le revisioni del servizio.

gcloud

Per eliminare un servizio, esegui questo comando:

gcloud run services delete SERVICE --region REGION

Sostituisci quanto segue:

• SERVICE: il nome del servizio.
• REGION: Google Cloud regione del servizio.

Eliminare il progetto di test

L'eliminazione del progetto Google Cloud interrompe la fatturazione per tutte le risorse al suo interno. Per rilasciare tutte le risorse Google Cloud del progetto, segui questi passaggi:

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:
• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Elimina un progetto Google Cloud :

gcloud projects delete PROJECT_ID

Passaggi successivi

Per saperne di più sulla creazione di un container dal codice sorgente e sul push in un repository, consulta:

• Sviluppo dei servizi Cloud Run
• Creazione di container
• Testare un servizio Cloud Run localmente
• Deployment dal codice sorgente