1. Przegląd
W części 1 za pomocą Knowledge Catalog i DataScan udało nam się przekształcić chaotyczne, nieustrukturyzowane pliki PDF w przejrzyste, inteligentne i ustrukturyzowane tabele w BigQuery. Mamy teraz solidną hurtownię danych. W części 2 skonfigurowaliśmy AlloyDB jako podstawę transakcyjną i sfederowaliśmy z nią tabele BigQuery, tworząc ujednoliconą warstwę danych bez duplikowania ani jednego bajta.
Dziś budujemy mózg. Tworzymy aplikację z wieloma agentami – „FroyoOS Store Manager” – która działa na tej warstwie danych i odpowiada na pytania, sprawdza alergeny oraz przetwarza zamówienia na żywo.
Wyzwanie: oddzielenie AI od agenta
Podczas tworzenia agenta AI, który musi komunikować się z bazami danych, najczęstszym błędem jest wymuszanie logiki danych i AI bezpośrednio w aplikacji w Pythonie. Sprawia to, że aplikacja jest podatna na awarie, niezabezpieczona i niezwykle trudna w utrzymaniu w miarę rozwoju architektury danych.
Aby rozwiązać ten problem, używamy zestawu narzędzi Model Context Protocol (MCP). Zestaw narzędzi MCP pełni funkcję ujednoliconej warstwy abstrakcji danych. Operacje na bazie danych definiujemy deklaratywnie w prostym pliku tools.yaml. Wdrażamy ten zestaw narzędzi jako bezpieczny, bezserwerowy punkt końcowy w Google Cloud Run. Nasz agent AI po prostu łączy się z tym punktem końcowym i mówi: „Wykonaj narzędzie ‘place_order’”.
Potęga HTAP
Zanim zaczniemy tworzyć agenta, porozmawiajmy o tym, dlaczego w tytule tego posta jest mowa o HTAP (Hybrid Transactional/Analytical Processing).
W tradycyjnej architekturze, jeśli agent AI musiałby przetworzyć zamówienie użytkownika na żywo (transakcyjne zadanie OLTP) i porównać dane z tysięcy złożonych mapowań składników (analityczne zadanie OLAP), aplikacja w Pythonie musiałaby zarządzać połączeniami z 2 zupełnie różnymi bazami danych. Powoduje to duże opóźnienia, obciążenie związane z zabezpieczeniami i niestabilne zarządzanie stanem.
Dzięki natywnej federacji naszej hurtowni danych BigQuery bezpośrednio z PostgreSQL przekształciliśmy AlloyDB w potężną platformę HTAP. Dzięki tej architekturze HTAP nasz agent AI musi dziś komunikować się tylko z 1 punktem końcowym bazy danych. Może wstawiać transakcje na żywo do tabeli live_orders i jednocześnie uruchamiać złożone skanowanie analityczne w sfederowanym zbiorze danych BigQuery froyo_data bez duplikowania ani jednego bajta danych. Zobaczmy, jak udostępniamy ten silnik naszej AI.
Zacznijmy tworzyć!
Czego się nauczysz
- Jak skonfigurować klaster, instancję i sieć AlloyDB jednym kliknięciem
- Jak skonfigurować rozszerzenie, aby przygotować się do federacji
- Jak skonfigurować federację z BigQuery do AlloyDB
- Jak to przetestować
Wymagania
2. Zanim zaczniesz
Utwórz projekt
- W konsoli Google Cloud na stronie wyboru projektu wybierz lub utwórz projekt Google Cloud .
- Sprawdź, czy w projekcie w chmurze włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.
- Będziesz używać Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud. Kliknij Aktywuj Cloud Shell na górze konsoli Google Cloud.
- Po połączeniu z Cloud Shell sprawdź, czy uwierzytelnianie zostało już przeprowadzone, a projekt jest już ustawiony na Twój identyfikator projektu. Aby to zrobić, użyj tego polecenia:
gcloud auth list
- Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:
gcloud config list project
- Jeśli chcesz się uwierzytelnić:
gcloud auth login
- Jeśli projekt nie jest ustawiony, użyj tego polecenia, aby go ustawić:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project <YOUR_PROJECT_ID>
- Włącz wymagane interfejsy API: aby włączyć wszystkie wymagane interfejsy API, uruchom to polecenie:
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
Pułapki i rozwiązywanie problemów
Syndrom „projektu widma” | Uruchomiłeś(-aś) polecenie |
Bariera płatności | Włączono projekt, ale zapomniano o koncie rozliczeniowym. AlloyDB to silnik o wysokiej wydajności. Nie uruchomi się, jeśli „zbiornik paliwa” (płatności) jest pusty. |
Opóźnienie propagacji interfejsu API | Kliknięto „Włącz interfejsy API”, ale w wierszu poleceń nadal wyświetla się komunikat |
Limity | Jeśli używasz nowego konta próbnego, możesz napotkać regionalny limit instancji AlloyDB. Jeśli |
3. Przygotowywanie danych
Upewnij się, że dane strukturalne wyodrębnione z nieustrukturyzowanych plików PDF są dostępne w BigQuery, a federacja BigQuery z AlloyDB jest skonfigurowana i przetestowana. Jeśli nie udało Ci się wykonać tych czynności, teraz jest dobry moment, aby wykonać proste kroki opisane tutaj i tutaj w częściach 1 i 2 odpowiednio.
Uwaga:
Jeśli wykonujesz to ćwiczenie, nie powinieneś(-aś) wykonywać kroku czyszczenia z części 2 (usuwania klastra i instancji), ponieważ potrzebujemy orkiestracji AlloyDB w naszym systemie agentowym, który jest tu przedstawiony.
Oprócz danych utworzonych w części 2 musimy utworzyć jeszcze 1 tabelę w instancji AlloyDB. Otwórz AlloyDB Studio, klikając ten link:
https://console.cloud.google.com/alloydb/locations/us-central1/clusters/my-alloydb-cluster/studio
Jeśli używasz innego klastra, zmień jego nazwę w linku powyżej.
W AlloyDB Studio na nowej karcie edytora zapytań uruchom to polecenie:
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
);
Powinno to utworzyć w Twojej bazie danych tabelę live_orders.
4. Definiowanie abstrakcji (tools.yaml)
Najpierw formalnie rejestrujemy operacje na bazie danych. Tworzymy plik tools.yaml, który określa, jak nasz agent wchodzi w interakcję z AlloyDB zawierającą zarówno dane transakcyjne, jak i analityczne (dane analityczne z federacji BigQuery).
- Otwórz terminal Cloud Shell. Przełącz na tryb edycji.
- Utwórz w katalogu głównym nowy folder: "froyo-agent"
- W folderze utwórz plik tools.yaml i wklej do niego tę treść (zastąp wartości projektu, klastra, instancji i hasła własnymi):
# 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
Ograniczyliśmy możliwości agenta do 2 narzędzi – sprawdzania alergenów i składania zamówień.
5. Wdrażanie zestawu narzędzi w Cloud Run
Aby udostępnić go naszej aplikacji, bezpiecznie wdrażamy zestaw narzędzi za pomocą gcloud CLI. Tworzy to punkt końcowy naszej warstwy abstrakcji.
- Przełącz na terminal Cloud Shell i przejdź do katalogu roboczego, uruchamiając to polecenie:
cd froyo-agent
- Zapisz plik tools.yaml w tajnym pliku o nazwie „tools-froyo”:
gcloud secrets create tools-froyo --data-file=tools.yaml
- Wdróż kontener MCP Toolbox w 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
Jeśli używasz wartości innych niż te, które skonfigurowaliśmy w ćwiczeniu z części 2, musisz zastąpić wartości „network” i „subnet”.
- Zapisz wynikowy adres URL Cloud Run (np. https://toolbox-froyo-xxx.run.app).
6. Backend agentowy (app.py)
Dzięki abstrakcji bazy danych nasz kod w Pythonie może się w całości skupić na orkiestracji i wnioskowaniu.
Używamy pakietu Agent Development Kit (ADK) razem z Flask. ADK zapewnia pamięć sesji klasy korporacyjnej (InMemorySessionService), co oznacza, że nasz agent pamięta kontekst rozmowy. Natywnie integruje się z ToolboxSyncClient , aby bezproblemowo pobierać nasze narzędzia z Cloud Run.
Oto Twój plik app.py:
https://github.com/AbiramiSukumaran/froyo-data/blob/main/app.py
Prosta aplikacja Flask w Pythonie łączy agenta ADK z narzędziami zdefiniowanymi w naszym zestawie narzędzi, który z kolei wchodzi w interakcję z AlloyDB (a także ze sfederowanymi danymi BigQuery) i odpowiada użytkownikowi.
7. Interfejs i uruchamianie aplikacji
Aby zapewnić naszym kierownikom sklepu odpowiednie wrażenia, stworzyliśmy elegancki, szklany interfejs (templates/index.html) z bocznym paskiem katalogu produktów na żywo i interaktywnym interfejsem czatu.
Plik index.html znajdziesz w repozytorium tutaj:
https://github.com/AbiramiSukumaran/froyo-data/blob/main/templates/index.html
Zanim uruchomisz aplikację, upewnij się, że masz zainstalowane zależności. Aby to zrobić, utwórz plik requirements.txt z tą treścią:
Flask>=3.0.0
google-genai>=0.1.0
mcp>=1.0.0
google-adk
toolbox-core
toolbox-langchain
python-dotenv
i wypełnij plik .env:
GOOGLE_API_KEY=***
MCP_TOOLBOX_SERVER_URL=***
W terminalu Cloud Shell, upewniając się, że jesteś w folderze projektu, uruchom kolejno te polecenia:
Zainstaluj zależności:
pip install -r requirements.txt
Wykonuję plik w Pythonie:
python app.py
Kliknij link, który pojawi się w terminalu, lub otwórz adres http://localhost:8080.
8. Ostateczny test
Kliknij produkt w katalogu, aby zadać agentowi pytanie:
Does Midnight Swirl have any allergens?
Powinna się wyświetlić ta odpowiedź:
Sceny zza kulis:
- Agent ADK otrzymuje prośbę i decyduje się użyć narzędzia check_allergens.
- Bezpiecznie wywołuje MCP Toolbox w Cloud Run.
- Zestaw narzędzi wykonuje zapytanie w AlloyDB, która natychmiast federuje się z BigQuery, aby przeskanować złożone relacje utworzone w części 1.
- Baza danych zwraca „Soy” (Soja), które agent zgrabnie podsumowuje w interfejsie.
Następnie mówimy:
Order 2 Midnight Swirls for Alice.
Agent przekazuje ciąg znaków „Midnight Swirl” do zestawu narzędzi. Podstawowy kod SQL dynamicznie przekształca ciąg znaków na identyfikator liczbowy za pomocą BigQuery, wstawia zamówienie na żywo do AlloyDB i potwierdza transakcję.
Repozytorium kodu
9. Zwalnianie miejsca
Po zakończeniu tego ćwiczenia nie zapomnij usunąć klastra i instancji AlloyDB.
Powinno to usunąć klaster wraz z jego instancjami.
10. Gratulujemy agenta!
Zastanów się, co właśnie udało nam się osiągnąć:
Nasz dobrze zorganizowany system agentowy wchodzi w interakcję tylko z MCP Toolbox for Databases. Za kulisami obsługuje on wywołanie narzędzia i dane do logiki AI naszej aplikacji, dzięki czemu przepływ jest prosty:
- Nasza aplikacja transakcyjna (działająca w AlloyDB) może obsługiwać szybkie, równoczesne sesje użytkowników.
- Gdy potrzebuje złożonych danych analitycznych lub kontekstu historycznego (np. szczegółów dostawcy lub złożonych mapowań składników), wysyła zapytanie do schematu froyo_data w BigQuery.
- Zero ETL. Brak awarii potoków danych. Brak niesynchronizowanych baz danych. Przechowujemy dane raz (w BQ) i przetwarzamy je tam, gdzie są potrzebne.
Nasz agent i podstawa danych – zarówno analitycznych, jak i transakcyjnych – są już gotowe, więc możemy przejść do następnej części.
Co dalej?
Nasz agent działa doskonale... w optymalnych warunkach. W części 4 utworzymy potok oceny agenta, aby dokładnie przetestować jego poprawność, ugruntowanie i wydajność. Do zobaczenia!