Creare un'app multi-agente con MCP Toolbox per AlloyDB e ADK

1. Panoramica

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à.

Quando la tua applicazione ha più agenti che lavorano insieme in modo autonomo e congiunto, se necessario, per soddisfare il suo scopo più ampio, e ognuno di questi agenti è indipendente e responsabile di un'area di interesse specifica, la tua applicazione diventa un sistema multi-agente.

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, 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 maggiore modularità, specializzazione, riusabilità, gestibilità e la possibilità di definire flussi di controllo strutturati utilizzando agenti del workflow dedicati.

Aspetti da tenere presenti per un sistema multi-agente

Innanzitutto, è importante avere una comprensione e un ragionamento adeguati della specializzazione di ogni agente. — "Sai perché hai bisogno di un subagente specifico per qualcosa?", scoprilo prima.

Secondo, come raggrupparli con un agente principale per indirizzare e dare un senso a ciascuna delle risposte.

Terzo, esistono diversi tipi di routing degli agenti che puoi trovare qui in questa documentazione. Scegli quello più adatto al flusso della tua applicazione. Inoltre, quali sono i vari contesti e stati necessari per il controllo del flusso del sistema multi-agente.

Cosa creerai

Creiamo un sistema multi-agente per gestire le ristrutturazioni della cucina utilizzando MCP Toolbox per AlloyDB e ADK.

Renovation Proposal Agent
Agente di controllo di permessi e conformità
Controllo dello stato dell'ordine (strumento che utilizza MCP Toolbox per database)

Agente per la proposta di ristrutturazione, per generare il documento della proposta di ristrutturazione della cucina.

Agente per permessi e conformità, per occuparsi di permessi e attività correlate alla conformità.

Agente di controllo dello stato dell'ordine, per controllare lo stato dell'ordine dei materiali lavorando sul database di gestione degli ordini che abbiamo configurato in AlloyDB. Per questa parte del database, utilizzeremo MCP Toolbox for AlloyDB per implementare la logica di recupero dello stato degli ordini.

2. MCP

MCP è l'acronimo di Model Context Protocol, uno standard aperto sviluppato da Anthropic che fornisce un modo coerente per gli agenti AI di connettersi a strumenti, servizi e dati esterni. Funziona essenzialmente come uno standard comune per le applicazioni AI, consentendo loro di interagire senza problemi con diverse origini dati e strumenti.

Utilizza un modello client-server in cui le applicazioni AI (gli host) eseguono il client MCP, che comunica con i server MCP.
Quando un agente AI deve accedere a uno strumento o a dati specifici, invia una richiesta strutturata al client MCP, che la inoltra al server MCP appropriato.
Consente ai modelli di AI di accedere a dati e strumenti esterni senza richiedere codice personalizzato per ogni integrazione.
Semplifica il processo di creazione di agenti e flussi di lavoro complessi basati su modelli linguistici di grandi dimensioni (LLM).

MCP Toolbox per database

MCP Toolbox for Databases di Google è un server MCP open source per i database. È stato progettato pensando alla qualità di produzione e di livello aziendale. Ti consente di sviluppare strumenti più facilmente, rapidamente e in modo più sicuro gestendo le complessità come il raggruppamento delle connessioni, l'autenticazione e altro ancora.

Consenti agli agenti di accedere ai dati nel tuo database. Come?

Sviluppo semplificato:integra gli strumenti nel tuo agente con meno di 10 righe di codice, riutilizza gli strumenti tra più agenti o framework e implementa più facilmente nuove versioni degli strumenti.

Rendimento migliore: best practice come il pooling delle connessioni, l'autenticazione e altro ancora.

Maggiore sicurezza:autenticazione integrata per un accesso più sicuro ai tuoi dati

Osservabilità end-to-end:metriche e tracciamento pronti all'uso con supporto integrato per OpenTelemetry.

Devi sottolineare il fatto che questo è precedente a MCP.

MCP Toolbox for Databases si trova tra il framework di orchestrazione dell'applicazione agentica e il database, fornendo un control plane utilizzato per modificare, distribuire o richiamare gli strumenti. Semplifica la gestione degli strumenti fornendoti una posizione centralizzata per archiviarli e aggiornarli, consentendoti di condividerli tra agenti e applicazioni e di aggiornarli senza dover necessariamente rieseguire il deployment dell'applicazione.

Avremo un agente principale che coordina questi agenti in base al requisito.

Requisiti

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

3. 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 è abilitata per un progetto .

Inoltre, 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. Per riscattarlo, segui le istruzioni riportate qui. Tieni presente che questo link è valido solo fino alla fine di maggio per l'utilizzo.

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.
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

Esegui questo 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>

Abilita le seguenti API eseguendo questi comandi:

gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com \alloydb.googleapis.com

Assicurati di avere Python 3.9 o versioni successive
Consulta la documentazione per i comandi e l'utilizzo di gcloud.

4. Configurazione dell'ADK

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

Installa ADK

pip install google-adk

5. Struttura del progetto

Dal terminale Cloud Shell, esegui questi comandi uno alla volta per creare le cartelle root e di progetto:

mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent

Vai all'editor di Cloud Shell e crea la seguente struttura del progetto creando i file (inizialmente vuoti):

renovation-agent/
        __init__.py
        agent.py
        .env

6. Codice sorgente

Vai a init.py e aggiorna con i seguenti contenuti:

from . import agent

Vai a agent.py e aggiorna il file con i seguenti contenuti dal seguente percorso:

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py

In agent.py, importiamo le dipendenze necessarie, recuperiamo i parametri di configurazione dal file .env e definiamo root_agent che utilizza uno strumento per richiamare lo strumento della toolbox.

Vai a requirements.txt e aggiornalo con i contenuti di quanto segue:

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

7. Configurazione del database

In uno degli strumenti utilizzati da ordering_agent, chiamato "check_status", accediamo al database degli ordini AlloyDB per ottenere lo stato degli ordini. In questa sezione configureremo il cluster e l'istanza del database AlloyDB.

Crea un cluster e un'istanza

Vai alla pagina AlloyDB nella console Cloud. Un modo semplice per trovare la maggior parte delle pagine in Cloud Console è cercarle utilizzando la barra di ricerca della console.
Seleziona CREA CLUSTER da questa pagina:

Vedrai una schermata come quella riportata di seguito. Crea un cluster e un'istanza con i seguenti valori (assicurati che i valori corrispondano se cloni il codice dell'applicazione dal repository):

cluster id: "vector-cluster"
password: "alloydb"
Compatibile con PostgreSQL 16 / consigliata l'ultima versione
Region: "us-central1"
Networking: "default"

Quando selezioni la rete predefinita, viene visualizzata una schermata come quella riportata di seguito.

Seleziona CONFIGURA CONNESSIONE.

Da qui, seleziona "Utilizza un intervallo IP allocato automaticamente" e fai clic su Continua. Dopo aver esaminato le informazioni, seleziona CREA CONNESSIONE.

6. NOTA IMPORTANTE: assicurati di modificare l'ID istanza (che puoi trovare al momento della configurazione del cluster / dell'istanza) in

vector-instance. Se non riesci a modificarlo, ricorda di utilizzare l'ID istanza in tutti i riferimenti futuri.

In preparazione alla configurazione di Toolbox, abilitiamo la connettività IP pubblico nella nostra istanza AlloyDB in modo che il nuovo strumento possa accedere al database.
Vai alla sezione Connettività IP pubblico, seleziona la casella di controllo Abilita IP pubblico e inserisci l'indirizzo IP della tua macchina Cloud Shell.
Per ottenere l'IP della tua macchina Cloud Shell, vai al terminale Cloud Shell e inserisci ifconfig. Dal risultato, identifica l'indirizzo inet eth0 e sostituisci le ultime due cifre con 0.0 con una dimensione della maschera "/16". Ad esempio, "XX.XX.0.0/16", dove XX sono numeri.
Incolla questo IP nella casella di testo "Reti" delle reti esterne autorizzate della pagina di modifica dell'istanza.

Una volta configurata la rete, puoi continuare a creare il cluster. Fai clic su CREA CLUSTER per completare la configurazione del cluster come mostrato di seguito:

Tieni presente che la creazione del cluster richiederà circa 10 minuti. Una volta completata l'operazione, dovresti visualizzare una schermata che mostra la panoramica del cluster che hai appena creato.

Importazione dati

Ora è il momento di aggiungere una tabella con i dati del negozio. Vai ad AlloyDB, seleziona il cluster principale e poi AlloyDB Studio:

Potrebbe essere necessario attendere il completamento della creazione dell'istanza. Una volta creato, accedi ad AlloyDB utilizzando le credenziali che hai creato durante la creazione del cluster. Utilizza i seguenti dati per l'autenticazione a PostgreSQL:

Nome utente : "postgres"
Database : "postgres"
Password : "alloydb"

Una volta eseguita l'autenticazione in AlloyDB Studio, i comandi SQL vengono inseriti nell'editor. Puoi aggiungere più finestre dell'editor utilizzando il segno più a destra dell'ultima finestra.

Inserirai i comandi per AlloyDB nelle finestre dell'editor, utilizzando le opzioni Esegui, Formatta e Cancella in base alle esigenze.

Creare una tabella

Puoi creare una tabella utilizzando l'istruzione DDL riportata di seguito in AlloyDB Studio:

-- Table DDL for Procurement Material Order Status

CREATE TABLE material_order_status (
    order_id VARCHAR(50) PRIMARY KEY,
    material_name VARCHAR(100) NOT NULL,
    supplier_name VARCHAR(100) NOT NULL,
    order_date DATE NOT NULL,
    estimated_delivery_date DATE,
    actual_delivery_date DATE,
    quantity_ordered INT NOT NULL,
    quantity_received INT,
    unit_price DECIMAL(10, 2) NOT NULL,
    total_amount DECIMAL(12, 2),
    order_status VARCHAR(50) NOT NULL, -- e.g., "Ordered", "Shipped", "Delivered", "Cancelled"
    delivery_address VARCHAR(255),
    contact_person VARCHAR(100),
    contact_phone VARCHAR(20),
    tracking_number VARCHAR(100),
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    quality_check_passed BOOLEAN,  -- Indicates if the material passed quality control
    quality_check_notes TEXT,        -- Notes from the quality control check
    priority VARCHAR(20),            -- e.g., "High", "Medium", "Low"
    project_id VARCHAR(50),          -- Link to a specific project
    receiver_name VARCHAR(100),        -- Name of the person who received the delivery
    return_reason TEXT,               -- Reason for returning material if applicable
    po_number VARCHAR(50)             -- Purchase order number
);

Inserisci record

Copia l'istruzione della query insert dallo script database_script.sql menzionato sopra nell'editor.

Fai clic su Esegui.

Ora che il set di dati è pronto, configuriamo MCP Toolbox for Databases in modo che funga da control plane per tutte le nostre interazioni con il database degli ordini in AlloyDB.

8. Configurazione di MCP Toolbox per database

Toolbox si trova tra il framework di orchestrazione dell'applicazione e il database, fornendo un control plane utilizzato per modificare, distribuire o richiamare gli strumenti. Semplifica la gestione degli strumenti fornendo una posizione centralizzata per archiviarli e aggiornarli, consentendoti di condividerli tra agenti e applicazioni e di aggiornarli senza dover necessariamente rieseguire il deployment dell'applicazione.

Puoi notare che uno dei database supportati da MCP Toolbox for Databases è AlloyDB e, poiché l'abbiamo già eseguito il provisioning nella sezione precedente, procediamo con la configurazione di Toolbox.

Vai al terminale Cloud Shell e assicurati che il progetto sia selezionato e visualizzato nel prompt del terminale. Esegui il comando riportato di seguito dal terminale Cloud Shell per passare alla directory del progetto:

cd adk-renovation-agent

Esegui il comando riportato di seguito per scaricare e installare toolbox nella nuova cartella:

# see releases page for other versions
export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Vai all'editor di Cloud Shell (per la modalità di modifica del codice) e, nella cartella radice del progetto, aggiungi un file denominato "tools.yaml".

sources:
    alloydb-orders:
        kind: "alloydb-postgres"
        project: "<<YOUR_PROJECT_ID>>"
        region: "us-central1"
        cluster: "<<YOUR_ALLOYDB_CLUSTER>>"
        instance: "<<YOUR_ALLOYDB_INSTANCE>>"
        database: "<<YOUR_ALLOYDB_DATABASE>>"
        user: "<<YOUR_ALLOYDB_USER>>"
        password: "<<YOUR_ALLOYDB_PASSWORD>>"

tools:
  get-order-data:
    kind: postgres-sql
    source: alloydb-orders
    description: Get the status of an order based on the material description.
    parameters:
      - name: description
        type: string
        description: A description of the material to search for its order status.
    statement: |
      select order_status from material_order_status where lower(material_name) like lower($1) 
      LIMIT 1;

Nella parte della query (fai riferimento al parametro "statement" sopra), stiamo recuperando solo il valore del campo stato dell'ordine quando il nome del materiale corrisponde al testo di ricerca dell'utente.

Analizziamo il file tools.yaml

Le origini rappresentano le diverse origini dati con cui uno strumento può interagire. Un'origine rappresenta un'origine dati con cui uno strumento può interagire. Puoi definire le origini come una mappa nella sezione sources del file tools.yaml. In genere, una configurazione dell'origine contiene tutte le informazioni necessarie per connettersi al database e interagire con esso.

Gli strumenti definiscono le azioni che un agente può intraprendere, ad esempio leggere e scrivere in una sorgente. Uno strumento rappresenta un'azione che l'agente può intraprendere, ad esempio l'esecuzione di un'istruzione SQL. Puoi definire gli strumenti come una mappa nella sezione degli strumenti del file tools.yaml. In genere, uno strumento richiede un'origine su cui agire.

Per ulteriori dettagli sulla configurazione di tools.yaml, consulta questa documentazione.

Eseguiamo il server MCP Toolbox per database

Esegui questo comando (dalla cartella mcp-toolbox) per avviare il server:

./toolbox --tools-file "tools.yaml"

Ora, se apri il server in modalità di anteprima web sul cloud, dovresti essere in grado di vedere il server Toolbox in esecuzione con il nuovo strumento denominato get-order-data.

Per impostazione predefinita, il server MCP Toolbox viene eseguito sulla porta 5000. Utilizziamo Cloud Shell per testare questa funzionalità.

Fai clic su Anteprima web in Cloud Shell come mostrato di seguito:

Fai clic su Cambia porta e imposta la porta su 5000 come mostrato di seguito, poi fai clic su Cambia e visualizza anteprima.

Dovrebbe essere visualizzato l'output:

MCP Toolkit for Databases descrive un SDK Python per convalidare e testare gli strumenti, documentato qui. Saltiamo questo passaggio e passiamo direttamente all'Agent Development Kit (ADK) nella sezione successiva, che utilizzerà questi strumenti.

Eseguiamo il deployment del nostro Toolbox in Cloud Run

Per prima cosa, possiamo iniziare con il server MCP Toolbox e ospitarlo su Cloud Run. In questo modo avremo un endpoint pubblico che potremo integrare con qualsiasi altra applicazione e/o con le applicazioni dell'agente. Le istruzioni per l'hosting su Cloud Run sono disponibili qui. Ora esamineremo i passaggi chiave.

Avvia un nuovo terminale Cloud Shell o utilizzane uno esistente. Vai alla cartella del progetto in cui sono presenti il file binario della toolbox e tools.yaml, in questo caso adk-renovation-agent
Imposta la variabile PROJECT_ID in modo che punti all'ID progetto Google Cloud.

export PROJECT_ID="<<YOUR_GOOGLE_CLOUD_PROJECT_ID>>"

Attiva questi servizi Google Cloud

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

Creiamo un service account separato che fungerà da identità per il servizio Toolbox che verrà sottoposto a deployment su Google Cloud Run.

gcloud iam service-accounts create toolbox-identity

Ci stiamo anche assicurando che questo service account disponga dei ruoli corretti, ovvero la possibilità di accedere a Secret Manager e comunicare con AlloyDB

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/alloydb.client

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/serviceusage.serviceUsageConsumer

Caricheremo il file tools.yaml come secret:

gcloud secrets create tools --data-file=tools.yaml

Se hai già un secret e vuoi aggiornare la versione del secret, esegui il comando riportato di seguito:

gcloud secrets versions add tools --data-file=tools.yaml

Imposta una variabile di ambiente sull'immagine container che vuoi utilizzare per Cloud Run:

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

L'ultimo passaggio del comando di deployment familiare in Cloud Run:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

In questo modo dovrebbe iniziare il processo di deployment di Toolbox Server con il file tools.yaml configurato in Cloud Run. Se il deployment va a buon fine, dovresti visualizzare un messaggio simile al seguente:

Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.                                                                                                                                                                                     
  OK Creating Revision...                                                                                                                                                                                             
  OK Routing traffic...                                                                                                                                                                                               
  OK Setting IAM Policy...                                                                                                                                                                                            
Done.                                                                                                                                                                                                                 
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app

Ora puoi utilizzare lo strumento appena implementato nella tua applicazione con agenti.

Connettiamo lo strumento della cassetta degli attrezzi al nostro agente.

Abbiamo già creato l'origine per la nostra applicazione agente. Aggiorniamolo in modo da includere un nuovo strumento MCP Toolbox for Databases che abbiamo appena implementato in Cloud Run.

Osserva il file requirements.txt con l'origine del repository:

Stiamo includendo la dipendenza per MCP Toolbox for Databases in requirements.txt

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

Osserva il file agent.py con il codice del repository:

Stiamo includendo lo strumento che richiama l'endpoint della casella degli strumenti per recuperare i dati dell'ordine per un materiale specifico ordinato.

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py

9. 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 sarà in grado di 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 tua chiave API.

10. Configurazione delle variabili ENV

Imposta i valori per i parametri nel file .env del modello. 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>>

Sostituisci i segnaposto con i tuoi valori.

11. Esegui l'agente

Utilizzando il terminale, vai alla directory principale del progetto dell'agente:

cd renovation-agent

Installa le dipendenze:

pip install -r requirements.txt

Puoi eseguire questo comando nel terminale Cloud Shell per eseguire l'agente:

adk run .

Puoi eseguire il seguente comando per eseguirlo in una UI web di ADK di cui è stato eseguito il provisioning:

adk web

Prova con i seguenti prompt:

user>> 

Hello. Check order status for Cement Bags.

12. Risultato

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:

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.

14. Complimenti

Complimenti! Hai creato correttamente un'applicazione multiagente utilizzando ADK e MCP Toolbox per database. Per saperne di più, consulta la documentazione del prodotto: Agent Development Kit e MCP Toolbox per database.

Creare un'app multi-agente con MCP Toolbox per AlloyDB e ADK Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.