1. Panoramica
Nella parte 1, abbiamo trasformato correttamente i PDF caotici e non strutturati in tabelle pulite, intelligenti e strutturate in BigQuery utilizzando Knowledge Catalog e DataScan. Ora abbiamo un data warehouse solido. Nella parte 2, abbiamo configurato AlloyDB come backbone transazionale e abbiamo federato le nostre tabelle BigQuery, creando un livello di dati unificato senza duplicare un singolo byte.
Oggi costruiamo il cervello. Stiamo creando un'applicazione multi-agente, "FroyoOS Store Manager", che si basa su questo livello di dati per rispondere a domande, controllare gli allergeni ed elaborare gli ordini in tempo reale.
La sfida: disaccoppiare l'AI dall'agente
Quando crei un agente AI che deve comunicare con i database, l'anti-pattern più comune è forzare la logica dei dati e dell'AI direttamente nell'applicazione Python. Ciò rende la tua app fragile, non sicura e incredibilmente difficile da gestire man mano che la tua architettura dei dati cresce.
Per risolvere questo problema, utilizziamo Model Context Protocol (MCP) Toolbox. MCP Toolbox funge da livello di astrazione dei dati unificato. Definiamo le operazioni del database in modo dichiarativo in un semplice file tools.yaml. Eseguiamo il deployment di questo toolbox come endpoint serverless sicuro su Google Cloud Run. Il nostro agente AI si connette semplicemente a questo endpoint e dice: "Esegui lo strumento "place_order".
Il potere di HTAP
Prima di iniziare a creare l'agente, parliamo del motivo per cui il titolo di questo post menziona specificamente l'elaborazione transazionale/analitica ibrida (HTAP).
In un'architettura tradizionale, se un agente AI doveva elaborare un ordine utente in tempo reale (un workload OLTP transazionale) ed eseguire un controllo incrociato su migliaia di mappature di ingredienti complesse (un workload OLAP analitico), la tua applicazione Python doveva gestire connessioni a due database completamente diversi. Ciò crea una latenza elevata, un overhead di sicurezza e una gestione dello stato fragile.
Abbiamo trasformato AlloyDB in un potente strumento HTAP federando in modo nativo il nostro data warehouse BigQuery direttamente in PostgreSQL. Grazie a questa architettura HTAP, il nostro agente AI oggi deve comunicare solo con un endpoint di database. Può inserire transazioni live nella tabella live_orders ed eseguire scansioni analitiche pesanti sul set di dati federato BigQuery froyo_data nello stesso momento, senza duplicare un singolo byte di dati. Vediamo come esporre questo motore alla nostra AI.
Iniziamo a creare.
Obiettivi didattici
- Come configurare il cluster, l'istanza e il networking AlloyDB con un clic
- Come configurare l'estensione per prepararsi alla federazione
- Come configurare la federazione da BigQuery ad AlloyDB
- Prova
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 è abilitata per un progetto.
- Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
- 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 vuoi autenticarti
gcloud auth login
- Se il progetto non è impostato, utilizza il seguente comando per impostarlo:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project <YOUR_PROJECT_ID>
- Abilita le API richieste: esegui questo comando per abilitare tutte le API richieste:
gcloud services enable \
alloydb.googleapis.com \
bigquery.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com \
compute.googleapis.com \
servicenetworking.googleapis.com
Aspetti da considerare e risoluzione dei problemi
La sindrome del "progetto fantasma" | Hai eseguito |
La barriera di fatturazione | Hai attivato il progetto, ma hai dimenticato l'account di fatturazione. AlloyDB è un motore ad alte prestazioni; non si avvia se il "serbatoio" (fatturazione) è vuoto. |
Ritardo di propagazione dell'API | Hai fatto clic su "Abilita API", ma la riga di comando indica ancora |
Quota Quags | Se utilizzi un account di prova nuovo di zecca, potresti raggiungere una quota regionale per le istanze AlloyDB. Se |
3. Preparazione dei dati
Assicurati che i dati strutturati estratti dai PDF non strutturati siano disponibili in BigQuery e che la federazione di dati BigQuery di AlloyDB sia stata stabilita e testata. Se non hai completato questi passaggi, è il momento di eseguire quelli semplici descritti qui e qui per le parti 1 e 2 rispettivamente.
Nota:
Se stai provando questo codelab, non devi eseguire il passaggio di pulizia della parte 2 (eliminazione del cluster e dell'istanza) perché abbiamo bisogno dell'orchestrazione di AlloyDB per il nostro sistema basato su agenti dimostrato qui.
Oltre a questi dati che abbiamo già creato nella parte 2, dobbiamo creare un'altra tabella nell'istanza AlloyDB. Vai ad AlloyDB Studio utilizzando il link:
https://console.cloud.google.com/alloydb/locations/us-central1/clusters/my-alloydb-cluster/studio
Se utilizzi un cluster diverso, modifica il nome del cluster nel link riportato sopra.
In AlloyDB Studio, in una nuova scheda dell'editor di query, esegui la seguente istruzione:
CREATE TABLE live_orders (
order_id SERIAL PRIMARY KEY,
customer_name VARCHAR(100),
product_id VARCHAR(100),
quantity INT,
order_status VARCHAR(50) DEFAULT 'Pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
In questo modo dovrebbe essere creata la tabella live_orders nel database.
4. Definizione dell'astrazione (il file tools.yaml)
Innanzitutto, registriamo formalmente le nostre operazioni di database. Creiamo un file tools.yaml che definisce il modo in cui il nostro agente interagisce con AlloyDB, che contiene sia i dati transazionali sia quelli analitici (dati analitici della federazione BigQuery).
- Vai al terminale Cloud Shell. Passa alla modalità Editor.
- Crea una nuova cartella nella directory principale: "froyo-agent"
- All'interno della cartella, crea un file tools.yaml e incolla i seguenti contenuti: (sostituisci con i tuoi valori per progetto, cluster, istanza e password)
# tools.yaml
sources:
alloydb-source:
kind: "alloydb-postgres"
project: "*******"
region: "us-central1"
cluster: "my-alloydb-cluster"
instance: "my-primary-inst"
database: "postgres"
user: "postgres"
password: "*******"
ipType: "private"
tools:
check_allergens:
kind: postgres-sql
source: alloydb-source
description: Queries the federated BigQuery tables to find allergens for a product.
statement: |
SELECT a.allergen_name
FROM consistsof c
INNER JOIN product p ON c.product_id = p.product_id
INNER JOIN ingredient i ON c.ingredient_id = i.ingredient_name
INNER JOIN containsallergen a ON i.ingredient_id = a.ingredient_id
WHERE UPPER(p.product_name) LIKE UPPER($1)
parameters:
- name: product_name
type: string
description: The name of the product to check. (e.g., '%Midnight%')
place_order:
kind: postgres-sql
source: alloydb-source
description: Inserts a new live transaction into the native AlloyDB orders table.
statement: |
INSERT INTO live_orders (customer_name, product_id, quantity)
VALUES ($1, (SELECT product_id FROM product WHERE product_name ILIKE '%' || $2 || '%' LIMIT 1), $3) RETURNING order_id;
parameters:
- name: customer_name
type: string
description: The name of the customer placing the order.
- name: product_name
type: string
description: The name of the product being ordered.
- name: quantity
type: integer
description: The quantity of the product being ordered.
toolsets:
alloydb_tools:
- check_allergens
- place_order
Abbiamo limitato le funzionalità dell'agente a due strumenti: controlla gli allergeni ed effettua l'ordine.
5. Deployment di Toolbox in Cloud Run
Per renderlo disponibile alla nostra applicazione, eseguiamo il deployment sicuro del toolbox utilizzando gcloud CLI. In questo modo viene creato l'endpoint del livello di astrazione.
- Passa al terminale Cloud Shell e vai alla directory di lavoro eseguendo il comando:
cd froyo-agent
- Salva tools.yaml in un secret denominato "tools-froyo":
gcloud secrets create tools-froyo --data-file=tools.yaml
- Esegui il deployment del container MCP Toolbox in Cloud Run
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
gcloud run deploy toolbox-froyo \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools-froyo:latest" \
--args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--network easy-alloydb-vpc \
--subnet easy-alloydb-subnet \
--allow-unauthenticated \
--vpc-egress private-ranges-only
I valori "network" e "subnet" devono essere sostituiti se hai utilizzato valori diversi da quelli configurati nel codelab della Parte 2.
- Prendi nota dell'URL Cloud Run risultante (ad es. https://toolbox-froyo-xxx.run.app).
6. Il backend agentico (app.py)
Con il nostro database astratto, il nostro codice Python può concentrarsi interamente sull'orchestrazione e sul ragionamento.
Utilizziamo Agent Development Kit (ADK) insieme a Flask. L'ADK fornisce una memoria di sessione di livello aziendale (InMemorySessionService), il che significa che il nostro agente ricorda il contesto della conversazione. Si integra in modo nativo con ToolboxSyncClient per estrarre facilmente i nostri strumenti da Cloud Run.
Ecco il tuo app.py:
https://github.com/AbiramiSukumaran/froyo-data/blob/main/app.py
La semplice app Python Flask connette l'agente ADK agli strumenti che abbiamo definito in Toolbox, che a sua volta interagisce con AlloyDB (e anche con i dati federati di BigQuery) e risponde all'utente.
7. L'interfaccia utente e l'esecuzione dell'app
Per offrire ai nostri Store Manager un'esperienza adeguata, abbiamo creato un'interfaccia utente elegante e glassmorfica (templates/index.html) con una barra laterale del catalogo dei prodotti live e un'interfaccia di chat interattiva.
Puoi trovare il file index.html nel file del repository qui:
https://github.com/AbiramiSukumaran/froyo-data/blob/main/templates/index.html
Prima di eseguire l'applicazione, assicurati di aver installato le dipendenze creando il file requirements.txt con i seguenti contenuti:
Flask>=3.0.0
google-genai>=0.1.0
mcp>=1.0.0
google-adk
toolbox-core
toolbox-langchain
python-dotenv
e il file .env compilato:
GOOGLE_API_KEY=***
MCP_TOOLBOX_SERVER_URL=***
Dal terminale Cloud Shell, assicurati di trovarti nella cartella del progetto ed esegui i seguenti comandi uno alla volta:
Installa le dipendenze:
pip install -r requirements.txt
Esecuzione del file Python:
python app.py
Fai clic sul link visualizzato nel terminale o apri http://localhost:8080.
8. The Ultimate Test
Facciamo clic su un prodotto del catalogo per chiedere all'agente:
Does Midnight Swirl have any allergens?
Dovresti vedere la risposta:
Dietro le quinte:
- L'agente ADK riceve il prompt e decide di utilizzare lo strumento check_allergens.
- Chiama in modo sicuro MCP Toolbox su Cloud Run.
- Toolbox esegue la query in AlloyDB, che viene federata immediatamente a BigQuery per analizzare le relazioni complesse che abbiamo creato nella Parte 1.
- Il database restituisce "Soy", che l'agente riassume in modo ordinato nella UI.
A questo punto, diciamo:
Order 2 Midnight Swirls for Alice.
L'agente passa la stringa "Midnight Swirl" alla casella degli strumenti. L'SQL sottostante risolve dinamicamente la stringa in un ID intero tramite BigQuery, inserisce l'ordine live in AlloyDB e conferma la transazione.
Code Repo
9. Esegui la pulizia
Una volta completato questo lab, non dimenticare di eliminare il cluster e l'istanza AlloyDB.
Dovrebbe liberare spazio nel cluster insieme alle relative istanze.
10. Congratulazioni per il tuo agente.
Pensa a cosa abbiamo appena realizzato:
Il nostro sistema agentico ben orchestrato interagisce solo con MCP Toolbox for Databases. Dietro le quinte, gestisce la chiamata allo strumento e i dati alla logica AI della nostra applicazione, mantenendo il flusso semplice:
- La nostra app transazionale (in esecuzione su AlloyDB) può gestire sessioni utente rapide e simultanee.
- Quando ha bisogno di dati analitici o di un contesto storico (come i dettagli del fornitore o mappature complesse degli ingredienti), esegue query sullo schema froyo_dataschema di BigQuery.
- Zero ETL. Nessuna interruzione delle pipeline di dati. Nessun database non sincronizzato. Archiviamo una sola volta (in BQ) e calcoliamo dove ci serve.
Ora che le basi dell'agente e dei dati, sia analitici che transazionali, sono complete, passiamo alla parte successiva.
Passaggi successivi
Il nostro agente funziona perfettamente… nel percorso felice. Nella Parte 4, creeremo una pipeline di valutazione dell'agente per testare rigorosamente la validità, la fondatezza e le prestazioni del nostro sistema di agenti. A presto!