Crea ed esegui il deployment di un agente di AI su Cloud Run utilizzando l'Agent Development Kit (ADK)

Il framework Agent Development Kit (ADK) semplifica la creazione, la valutazione e il deployment di agenti AI. ADK fornisce un approccio modulare e basato sul codice per la creazione di agenti in grado di ragionare, pianificare e utilizzare gli strumenti.

Questo tutorial mostra come creare ed eseguire il deployment di un agente AI in Cloud Run utilizzando ADK per Python. Questo agente recupera il report meteo per una città specificata.

Per saperne di più sull'hosting dell'agente ADK utilizzando Google Cloud CLI, consulta Esegui il deployment in Cloud Run nella documentazione di ADK.

Obiettivi

• Scrivi l'applicazione di esempio per definire l'agente meteo.
• Esegui il deployment dell'agente in Cloud Run dal codice sorgente.
• Esegui l'agente per eseguire query sulle informazioni meteo.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run
• Vertex AI

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi Google Cloud utenti potrebbero avere diritto a una prova senza costi.

Prima di iniziare

Accedi al tuo Google Cloud account. 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.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Abilita le API Cloud Run Admin, Vertex AI e Cloud Build.

   Ruoli richiesti per abilitare le API

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

   Abilita le API

2. Configura l'ambiente di sviluppo Cloud Run nel tuo Google Cloud progetto.
3. Installa ADK seguendo le istruzioni riportate nella documentazione di Agent Development Kit.

4. Se hai una policy dell'organizzazione con limitazione del dominio che limita le chiamate non autenticate per il tuo progetto, dovrai accedere al servizio di cui hai eseguito il deployment come descritto in Testare i servizi privati.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire il deployment di un agente AI in Cloud Run, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Cloud Run Source Developer (roles/run.sourceDeveloper) sul progetto
• Vertex AI User (roles/aiplatform.user) sul progetto
• Utente account di servizio (roles/iam.serviceAccountUser) sull'identità di servizio
• Logs Viewer (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.

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 alla 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' Google Cloud ID progetto.
   • 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 dal codice sorgente

Il deployment dal codice sorgente crea automaticamente un'immagine container dal codice sorgente ed esegue il deployment.

1. Nella directory del codice sorgente (parent_folder), esegui il deployment in 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 richiesta la regione, seleziona 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 limitazione del dominio che lo impedisce. Per maggiori dettagli, consulta la sezione Prima di iniziare.

   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 il seguente 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 il seguente 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 il seguente 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 Utilizzare il server API nella documentazione di ADK.

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

Libera spazio

Per evitare addebiti aggiuntivi sul tuo Google Cloud account, elimina tutte le risorse di cui hai eseguito il deployment con questo tutorial.

Elimina il progetto

Se hai creato un nuovo progetto per questo tutorial, eliminalo. Se hai utilizzato un progetto esistente e devi conservarlo senza le modifiche aggiunte in questo tutorial, elimina le risorse create per il tutorial.

Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai creato per il tutorial.

Per eliminare il progetto:

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.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella Google Cloud console, vai alla pagina Gestisci risorse.

   Vai a Gestisci risorse

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

Elimina le risorse del tutorial

1. Elimina il servizio Cloud Run di cui hai eseguito il deployment in questo tutorial. I servizi Cloud Run non comportano costi finché non ricevono richieste.

   Per eliminare il servizio Cloud Run, esegui il seguente comando:

   gcloud run services delete SERVICE-NAME

   Sostituisci SERVICE-NAME con il nome del servizio.

   Puoi eliminare i servizi Cloud Run anche dalla Google Cloud console.

2. Rimuovi la configurazione della regione predefinita di gcloud che hai aggiunto durante la configurazione del tutorial:

    gcloud config unset run/region
   

3. Rimuovi la configurazione del progetto:

    gcloud config unset project