Dai prototipi agli agenti con ADK

1. Panoramica

Da dove inizia oggi la creazione con l'AI? 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?". È qui che entra in gioco Google AI Studio. È un luogo in cui puoi creare rapidamente prototipi di qualsiasi cosa. Voglio ristrutturare la cucina e sono sicuro che Gemini possa aiutarmi, ma sono un ingegnere, non un appaltatore generale. Non so nemmeno cosa chiedere: ci sono così tante cose da considerare: regolamenti, impianti e così via. Quindi, analizziamo la situazione e chiediamo a Gemini di generare un prompt super dettagliato, quindi un piano di ristrutturazione completo e anche una visualizzazione della ristrutturazione. Ma aspetta. Come posso aiutare le attività a crescere da qui? Inserisci AGENTI!!!

Un agente è un programma autonomo che comunica con un modello di AI per eseguire un'operazione basata su un obiettivo utilizzando gli strumenti e il contesto a sua disposizione ed è in grado di prendere decisioni autonome basate sulla verità.

Agent Development Kit (ADK)

Agent Development Kit (ADK) è un framework flessibile e modulare per lo sviluppo e il deployment di agenti AI. 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 diversi agenti, spesso formando una gerarchia, collaborano o si coordinano per raggiungere un obiettivo più grande. La strutturazione dell'applicazione in questo modo offre vantaggi significativi, tra cui maggiore modularità, specializzazione, riutilizzabilità, manutenibilità e la possibilità di definire flussi di controllo strutturati utilizzando agenti di flusso di lavoro dedicati.

Cosa creerai

Vuoi passare dal nostro PROMPT prototipo alla creazione di un agente? Creeremo un agente per aiutarti a generare il documento della proposta per il progetto di ristrutturazione della cucina. Nell'ambito di questo lab, imparerai a:

  1. Crea un agente semplice per generare il documento Proposta di ristrutturazione con ADK
  2. Archivia il documento della proposta di ristrutturazione generato in un bucket Cloud Storage
  3. Testare l'agente in Cloud Shell e nell'output web dell'agente

Requisiti

  • Un browser, ad esempio Chrome o Firefox
  • Un progetto Google Cloud con la fatturazione abilitata.

2. Prima di iniziare

Crea un progetto

  1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
  2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto .
  3. Se stai leggendo questo articolo e vuoi ottenere dei crediti per iniziare a utilizzare Google Cloud e ADK, utilizza questo link per riscattare i crediti.
  4. Per riscattarlo, puoi seguire le istruzioni qui. Tieni presente che questo link è valido solo fino al 15 luglio 2025 per l'utilizzo.
  5. Attiva Cloud Shell facendo clic su questo link. Puoi passare dal terminale Cloud Shell (per eseguire comandi cloud) all'editor (per creare progetti) facendo clic sul pulsante corrispondente in Cloud Shell.
  6. Una volta eseguita la connessione a Cloud Shell, verifica di essere già autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:
gcloud auth list
  1. Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.
gcloud config list project
  1. Se il progetto non è impostato, utilizza il seguente comando per impostarlo:
gcloud config set project <YOUR_PROJECT_ID>
  1. Assicurati di avere Python 3.9 o versioni successive.

Per altri comandi gcloud e informazioni sull'utilizzo, consulta la documentazione.

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.

Partendo da questa semplice descrizione, Gemini mi ha fornito un prompt incredibilmente dettagliato per iniziare la ristrutturazione. In pratica, utilizziamo Gemini per ottenere risposte ancora migliori da AI Studio e dai nostri modelli. Puoi anche selezionare modelli diversi 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 in 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ò gestire richieste di contesto lunghe.

Vedi lo snippet della risposta di seguito:

4e4361663df80964.png

AI Studio ha analizzato i miei dati e ha prodotto tutti questi elementi come armadi, piani di lavoro, alzatina, pavimenti, lavello, 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.

  1. Copia questo prompt e incollalo nell'editor dei prompt:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
  1. Allega un'immagine della tua cucina attuale (o puoi utilizzare la mia immagine di cucina di esempio).
  2. Imposta il modello su "Generazione di immagini di anteprima di Gemini 2.0 Flash" per avere accesso alla generazione di immagini.

Ho ottenuto questo output:

fb33e7b1f6560a0c.png

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, recuperare la chiave API e scalarlo in un'applicazione agentica completa utilizzando la potenza di Vertex AI ADK.

4. Configurazione ADK

Ora passiamo al terminale Cloud Shell che abbiamo attivato nella sezione "Prima di iniziare":

  1. Crea e attiva l'ambiente virtuale (consigliato)

Dal terminale Cloud Shell, crea un ambiente virtuale:

python -m venv .venv

Attiva l'ambiente virtuale:

source .venv/bin/activate
  1. Installa ADK
pip install google-adk

5. Struttura del progetto

  1. Dal terminale Cloud Shell, crea una directory principale per le tue app agentiche nella posizione del progetto che preferisci:
mkdir agentic-apps
  1. All'interno della directory principale, crea una cartella specifica per il nostro progetto attuale:
mkdir renovation-agent
  1. Vai all'editor di Cloud Shell e crea la seguente struttura del progetto creando i file (inizialmente vuoti):
renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Codice sorgente

  1. Vai a "init.py" e aggiorna con i seguenti contenuti:
from . import agent
  1. Vai a agent.py e aggiorna il file con i seguenti contenuti dal seguente percorso:

In agent.py, importiamo le dipendenze necessarie, recuperiamo i parametri di configurazione dal file .env e definiamo root_agent che genera un documento di proposta e lo archivia in un bucket Cloud Storage. Per eseguire il passaggio di Cloud Storage, utilizziamo uno strumento chiamato store_pdf.

NOTA: al momento il PDF NON È FORMATTATO. In base alla PR della community di sviluppatori, il seguente snippet è stato incluso qui [non testato]. Puoi inserirlo nel metodo store_pdf:

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"
  1. Assicurati di avere il bucket Cloud Storage

Per memorizzare il documento della proposta generato dall'agente. Crealo e fornisci l'accesso in modo che il sistema agentico 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 gli assegni un altro nome, ricordati di aggiornare il valore di STORAGE_BUCKET nel file .env (nel passaggio di configurazione delle variabili ENV).

  1. 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 a Autorizzazioni -> Visualizza entità -> Concedi accesso. Seleziona Entità come "allUsers" e Ruolo come "Utente oggetti 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.
  1. Crea elenco delle dipendenze

Elenca tutte le dipendenze in requirements.txt. Puoi copiarlo da repo.

Spiegazione del codice sorgente del sistema di un singolo 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 dell'agente

Agente radice (Orchestrator): proposal_agent

L'agente root funge da orchestratore di questo sistema ad agente singolo. Riceve la richiesta di ristrutturazione iniziale e determina quali strumenti richiamare in base alle esigenze della richiesta.

L'agente principale raccoglie quindi le risposte dagli strumenti e le combina per fornire una risposta completa all'utente. In questo caso abbiamo solo uno strumento "store_pdf".

7. Flusso di dati e concetti chiave

L'utente avvia una richiesta tramite l'interfaccia ADK (il terminale o l'interfaccia utente web).

  1. La richiesta viene ricevuta da root_agent.
  2. L'agente root analizza la richiesta e la indirizza allo strumento come e quando richiesto.
  3. Lo strumento "store_pdf" è progettato per scrivere i contenuti di testo rinnovati in un file PDF, quindi caricarlo su Google Cloud Storage.
  4. che a sua volta restituisce la risposta a root_agent.
  5. L'agente root combina le risposte e fornisce un output finale all'utente.

LLM (modelli linguistici di grandi dimensioni)

Gli agenti si basano molto sugli LLM per generare testo, rispondere a domande ed eseguire attività di ragionamento. Gli LLM sono il "cervello" che consente agli 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 generata. Devi creare un bucket e concedere le autorizzazioni necessarie agli agenti per accedervi.

Cloud Run (facoltativo)

OrderingAgent utilizza una funzione Cloud Run per interfacciarsi con AlloyDB. Cloud Run fornisce un ambiente serverless per eseguire il codice in risposta alle richieste HTTP.

AlloyDB

Se utilizzi OrderingAgent, devi configurare un database AlloyDB per archiviare le informazioni sugli ordini.

File.env

Il file .env archivia informazioni sensibili come chiavi API, credenziali del database e nomi dei bucket. È fondamentale mantenere questo file sicuro e non eseguirne il commit nel repository. Memorizza anche le impostazioni di configurazione per gli agenti e il tuo progetto Google Cloud. La funzione root_agent o le funzioni di supporto in genere leggono i valori da questo file. Assicurati che tutte le variabili richieste siano impostate correttamente nel file .env. che include 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 negherà le richieste dell'agente e quest'ultimo non potrà funzionare.

  1. Ottieni una chiave API da Google AI Studio.
  2. Nel passaggio successivo, in cui configuri il file .env, sostituisci <<your API KEY>> con il valore effettivo della tua chiave API.

9. Configurazione delle variabili di ambiente

  1. Configura i valori per i parametri nel file .env del modello in questo repository. Nel mio caso, il file .env contiene queste 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

  1. Utilizzando il terminale, vai alla directory principale del progetto dell'agente:
cd agentic-apps/renovation-agent
  1. Installa tutte le dipendenze
pip install -r requirements.txt
  1. Puoi eseguire questo comando nel terminale Cloud Shell per eseguire l'agente:
adk run .
  1. Puoi eseguire il seguente comando per eseguirlo in una UI web di ADK di cui è stato eseguito il provisioning:

Nota: devi eseguire questo comando al di fuori della cartella del progetto dell'agente, uscire dalla cartella ed eseguirlo:

adk web
  1. 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"

2703603a907329ae.png

ae56b38cc6da9afe.png

…

91452a4de933a75b.png

Puoi verificare se il documento Proposta di ristrutturazione è stato creato nel bucket Cloud Storage.

12. Esegui il deployment in Cloud Run

  1. Crea un file denominato Dockerfile all'interno della cartella radice del progetto:
cd agentic-apps/renovation-agent
  1. Copia i contenuti dal repository GitHub
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

in questo file Dockerfile.

  1. Esegui il deployment su Cloud Run utilizzando questo comando:
adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

È tutto. Una volta eseguito il deployment, dovresti visualizzare l'endpoint nel terminale, pronto per l'uso.

13. Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo post, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina 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.

14. Complimenti

Complimenti! Hai creato e interagito correttamente con la tua app multiagente utilizzando ADK. Il sistema multi-agente è progettato per semplificare il processo 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 l'agente principale coordina le sue attività per fornire una soluzione completa. Il sistema sfrutta LLM, servizi Google Cloud e potenzialmente API esterne per fornire le sue funzionalità. Qui trovi un link alla documentazione del prodotto.