Informazioni su questo codelab
1. Panoramica
Da dove si inizia oggi a creare con l'IA? Per la maggior parte di noi, spesso inizia con una semplice domanda: "Il modello può davvero aiutarmi a risolvere questo problema a cui sto pensando?". Ed è qui che entra in gioco Google AI Studio. È un luogo in cui puoi creare rapidamente prototipi di qualsiasi cosa. Vorrei ristrutturare la mia cucina e scommetto che Gemini può aiutarmi, ma sono un ingegnere, non un appaltatore generale. Non so nemmeno cosa chiedere, ci sono così tanti aspetti da considerare: normative, impianti e così via. Analizziamo la situazione e chiediamo a Gemini di generare un prompt molto dettagliato, poi un piano di ristrutturazione completo e anche di visualizzare la ristrutturazione. Ma aspetta. Come posso aiutare le aziende a crescere? Inserisci AGENTS!!!
Un agente è un programma autonomo che interagisce con un modello di IA per eseguire un'operazione basata sugli obiettivi utilizzando gli strumenti e il contesto a sua disposizione ed è in grado di prendere decisioni autonome basate su dati reali.
Agent Development Kit (ADK)
Agent Development Kit (ADK) è un framework flessibile e modulare per lo sviluppo e il deployment di agenti di IA. ADK supporta la creazione di applicazioni sofisticate componendo più istanze di agenti distinte in un sistema multi-agente (MAS).
In ADK, un sistema multi-agente è un'applicazione in cui agenti diversi, che spesso formano una gerarchia, collaborano o si coordinano per raggiungere un obiettivo più grande. La strutturazione dell'applicazione in questo modo offre vantaggi significativi, tra cui modularità, specializzazione, riutilizzabilità e manutenibilità avanzate, nonché la possibilità di definire flussi di controllo strutturati utilizzando agenti di flusso di lavoro dedicati.
Cosa creerai
Sei pronto a passare dal nostro prototipo PROMPT alla creazione di un agente? Creeremo un agente per aiutarti a generare il documento della proposta per il progetto di ristrutturazione della cucina. In questo lab imparerai a:
- Crea un agente semplice per generare un documento di proposta di ristrutturazione con ADK
- Archivia il documento della proposta di ristrutturazione generato in un bucket Cloud Storage
- Testare l'agente in Cloud Shell e nell'output web dell'agente
Requisiti
2. Prima di iniziare
Crea un progetto
- Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
- Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è attivata in un progetto .
- Inoltre, se stai leggendo questo articolo e vuoi ricevere alcuni crediti per iniziare a utilizzare Google Cloud e ADK, utilizza questo link per riscattare i crediti.
- Puoi seguire le istruzioni qui per utilizzarlo. Tieni presente che questo link è valido solo fino al 15 luglio 2025 per l'utilizzo.
- Attiva Cloud Shell facendo clic su questo link. Puoi passare dal terminal Cloud Shell (per eseguire comandi cloud) all'editor (per compilare i progetti) facendo clic sul pulsante corrispondente in Cloud Shell.
- Una volta connesso a Cloud Shell, verifica di aver già eseguito l'autenticazione e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:
gcloud auth list
- Esegui il seguente comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.
gcloud config list project
- Se il progetto non è impostato, utilizza il seguente comando per impostarlo:
gcloud config set project <YOUR_PROJECT_ID>
- Assicurati di avere Python 3.9 o versioni successive
Consulta la documentazione per altri comandi e utilizzi di gcloud.
3. Prototipo
Vai a Google AI Studio. Inizia a digitare il prompt. Ecco il mio prompt:
I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.
Modifica e configura i parametri sul lato destro per ottenere una risposta ottimale.
In base a questa semplice descrizione, Gemini mi ha fornito un prompt incredibilmente dettagliato per iniziare i lavori di ristrutturazione. In pratica, utilizziamo Gemini per ottenere risposte ancora migliori da AI Studio e dai nostri modelli. Puoi anche selezionare diversi modelli da utilizzare, in base al caso d'uso.
Abbiamo scelto Gemini 2.5 Pro. Si tratta di un modello di pensiero, il che significa che otteniamo ancora più token di output, in questo caso fino a 65.000 token, per analisi nel formato lungo e documenti dettagliati. La casella di pensiero di Gemini viene visualizzata quando attivi Gemini 2.5 Pro, che dispone di funzionalità di ragionamento native e può accettare richieste di contesto lunghe.
Guarda lo snippet della risposta di seguito:
AI Studio ha analizzato i miei dati e ha prodotto tutti questi elementi, come armadi, piani di lavoro, paraschizzi, pavimenti, lavelli, coesione, tavolozza dei colori e selezione dei materiali. Gemini cita persino le fonti.
Ora prova a vedere l'idea prendere vita con un prompt diverso.
- Copia questa richiesta e incollala nell'editor di prompt:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
- Allega un'immagine della tua cucina attuale (in alternativa, puoi utilizzare la mia immagine di cucina di esempio).
- Modifica il modello in "Gemini 2.0 Flash Preview Image Generation" per avere accesso alla generazione di immagini.
Ho ottenuto questo output:
Questo è il potere di Gemini.
Dalla comprensione dei video alla generazione di immagini native fino alla verifica delle informazioni reali con la Ricerca Google, ci sono cose che possono essere create solo con Gemini.
Da AI Studio, puoi prendere questo prototipo, acquisire la chiave API e scalarlo in un'applicazione agente completa utilizzando la potenza dell'SDK Vertex AI.
4. Configurazione dell'ADK
Ora passiamo al terminale Cloud Shell che abbiamo attivato nella sezione "Prima di iniziare":
- Crea e attiva l'ambiente virtuale (opzione consigliata)
Dal terminale Cloud Shell, crea un ambiente virtuale:
python -m venv .venv
Attiva l'ambiente virtuale:
source .venv/bin/activate
- Installa ADK
pip install google-adk
5. Struttura del progetto
- Dal terminale Cloud Shell, crea una directory principale per le app agenti nella posizione del progetto che preferisci:
mkdir agentic-apps
- All'interno della directory principale, crea una cartella specifica per il nostro progetto attuale:
mkdir renovation-agent
- Vai all'editor di Cloud Shell e crea la seguente struttura di progetto creando i file (vuoti all'inizio):
renovation-agent/
__init__.py
agent.py
requirements.txt
.env
6. Codice sorgente
- Vai a "init.py" e aggiornalo con i seguenti contenuti:
from . import agent
- Vai ad agent.py e aggiorna il file con i seguenti contenuti dal seguente percorso:
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py
In agent.py importiamo le dipendenze necessarie, recuperiamo i parametri di configurazione dal file .env e definiamo root_agent che genera un documento della proposta e lo archivia in un bucket Cloud Storage. Per eseguire il passaggio di Cloud Storage, utilizziamo uno strumento chiamato store_pdf.
- Assicurati di avere il bucket Cloud Storage
Per memorizzare il documento della proposta generato dall'agente. Crealo e esegui il provisioning dell'accesso in modo che il sistema di agenti che creiamo con Vertex AI possa accedervi. Ecco come fare:
https://cloud.google.com/storage/docs/creating-buckets#console
Assegna al bucket il nome "next-demo-store
". Se lo chiami in un altro modo, ricordati di aggiornare il valore di STORAGE_BUCKET nel file .env (nel passaggio di configurazione delle variabili ENV).
- Per configurare l'accesso al bucket, vai alla console Cloud Storage e al tuo bucket di archiviazione (nel nostro caso il nome del bucket è "next-demo-storage": https://console.cloud.google.com/storage/browser/next-demo-storage.
Vai ad Autorizzazioni -> Visualizza entità -> Concedi accesso. Seleziona entità come "allUsers" e ruolo come "Utente oggetto Storage".
Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
- Creare un elenco di dipendenze
Elenca tutte le dipendenze in requirements.txt. Puoi copiarlo dal repo.
Spiegazione del codice sorgente del sistema con un solo agente
Il file agent.py definisce la struttura e il comportamento del nostro sistema multi-agente di ristrutturazione della cucina utilizzando l'Agent Development Kit (ADK). Analizziamo i componenti chiave:
Definizione agente
Agente principale (Orchestrator): proposal_agent
root_agent funge da orchestratore di questo sistema a un solo agente. Riceve la richiesta di ristrutturazione iniziale e determina quali strumenti richiamare in base alle esigenze della richiesta.
root_agent raccoglie quindi le risposte degli strumenti e le combina per fornire una risposta completa all'utente. In questo caso abbiamo un solo strumento "store_pdf".
7. Flusso di dati e concetti chiave
L'utente avvia una richiesta tramite l'interfaccia ADK (terminale o interfaccia utente web).
- La richiesta viene ricevuta da root_agent.
- root_agent analizza la richiesta e la inoltra allo strumento in base alle necessità.
- Lo strumento "store_pdf" è progettato per scrivere i contenuti di testo rinnovati in un file PDF e poi caricarlo su Google Cloud Storage.
- La risposta viene quindi restituita a root_agent.
- root_agent combina le risposte e fornisce un output finale all'utente.
Modelli linguistici di grandi dimensioni (LLM)
Gli agenti si basano molto sugli LLM per generare testo, rispondere a domande ed eseguire attività di ragionamento. Gli LLM sono il "cervello" che sta dietro la capacità degli agenti di comprendere e rispondere alle richieste degli utenti. In questa applicazione utilizziamo Gemini 2.5.
Google Cloud Storage
Utilizzato per archiviare i documenti della proposta di ristrutturazione generati. Devi creare un bucket e concedere le autorizzazioni necessarie per consentire agli agenti di accedervi.
Cloud Run (facoltativo)
OrderingAgent utilizza una funzione Cloud Run per interfacciarsi con AlloyDB. Cloud Run fornisce un ambiente serverless per eseguire codice in risposta alle richieste HTTP.
AlloyDB
Se utilizzi OrderingAgent, devi configurare un database AlloyDB per archiviare i dati degli ordini.
File.env
Il file .env memorizza informazioni sensibili come chiavi API, credenziali del database e nomi dei bucket. È fondamentale mantenere questo file al sicuro e non eseguirlo nel tuo repository. Memorizza anche le impostazioni di configurazione per gli agenti e il tuo progetto Google Cloud. In genere, root_agent o le funzioni di supporto leggono i valori da questo file. Assicurati che tutte le variabili richieste siano impostate correttamente nel file .env. incluso il nome del bucket Cloud Storage
8. Configurazione del modello
La capacità dell'agente di comprendere le richieste degli utenti e generare risposte è basata su un modello linguistico di grandi dimensioni (LLM). L'agente deve effettuare chiamate sicure a questo servizio LLM esterno, che richiede credenziali di autenticazione. Senza un'autenticazione valida, il servizio LLM rifiuterà le richieste dell'agente, che non potrà funzionare.
- Ottieni una chiave API da Google AI Studio.
- Nel passaggio successivo, in cui configuri il file .env, sostituisci
<<your API KEY>>
con il valore effettivo della chiave API.
9. Configurazione delle variabili di ambiente
- Configura i valori per i parametri nel file .env del modello in questo repo. Nel mio caso, il file .env contiene le seguenti variabili:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>
Sostituisci i segnaposto con i tuoi valori.
10. Esegui l'agente
- Utilizzando il terminale, vai alla directory principale del progetto dell'agente:
cd agentic-apps/renovation-agent
- Installa tutte le dipendenze
pip install -r requirements.txt
- Per eseguire l'agente, puoi eseguire il seguente comando nel terminale Cloud Shell:
adk run .
- Per eseguirlo in un'interfaccia utente web di cui è stato eseguito il provisioning in ADK, puoi eseguire quanto segue:
adk web
- Fai una prova con i seguenti prompt:
user>>
Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.
11. Risultato
Per il comando adk run . Il risultato è il seguente"
…
Puoi verificare se il documento della proposta di ristrutturazione è stato creato nel bucket Cloud Storage.
12. Esegui la pulizia
Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo post, segui questi passaggi:
- Nella console Google Cloud, vai alla pagina Gestisci risorse.
- Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
- Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.
13. Complimenti
Complimenti! Hai creato e interagito correttamente con la tua app multi-agente utilizzando ADK. Il sistema multi-agente è progettato per semplificare la procedura di ristrutturazione della cucina automatizzando attività come la generazione di proposte, il controllo dei permessi e il monitoraggio dello stato degli ordini. Ogni agente ha un ruolo specifico e root_agent coordina le loro attività per fornire una soluzione completa. Il sistema sfrutta i modelli LLM, i servizi Google Cloud e potenzialmente API esterne per fornire le sue funzionalità. Qui trovi un link alla documentazione del prodotto.