1. Wprowadzenie
W tym ćwiczeniu utworzysz agenta za pomocą ADK opartego na Gemini 3.5 Flash. Agent będzie wyposażony w narzędzia z 2 zdalnych (hostowanych przez Google) serwerów MCP, które zapewnią bezpieczny dostęp do BigQuery w celu uzyskania danych demograficznych, cenowych i sprzedażowych oraz do Map Google na potrzeby analizy i weryfikacji lokalizacji w świecie rzeczywistym.
Agent koordynuje żądania między użytkownikiem a usługami Google Cloud, aby rozwiązywać problemy biznesowe związane z fikcyjnym zbiorem danych piekarni.
Co zrobisz
- Skonfigurujesz dane: utworzysz podstawowy zbiór danych piekarni w BigQuery.
- Opracujesz agenta: utworzysz inteligentnego agenta za pomocą pakietu Agent Development Kit (ADK).
- Zintegrujesz narzędzia: wyposażysz agenta w funkcje BigQuery i Map za pomocą serwera MCP.
- Przeanalizujesz rynek: będziesz wchodzić w interakcje z agentem, aby ocenić trendy rynkowe i nasycenie rynku.
Czego potrzebujesz
- Przeglądarka internetowa, np. Chrome.
- Projekt Google Cloud z włączonymi płatnościami lub konto Gmail.
To ćwiczenie jest przeznaczone dla deweloperów na wszystkich poziomach, w tym dla początkujących. Do tworzenia ADK będziesz używać interfejsu wiersza poleceń w Google Cloud Shell i kodu w Pythonie. Nie musisz być ekspertem w Pythonie, ale podstawowa wiedza o tym, jak czytać kod, pomoże Ci zrozumieć koncepcje.
2. Zanim zaczniesz
Utwórz projekt Google Cloud
- W konsoli Google Cloud na stronie wyboru projektu wybierz lub utwórz projekt w chmurze 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.
Uruchom Cloud Shell
Cloud Shell to środowisko wiersza poleceń działające w Google Cloud, które jest wstępnie załadowane niezbędnymi narzędziami.
- U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell.
- Po połączeniu z Cloud Shell uruchom to polecenie, aby sprawdzić uwierzytelnianie w Cloud Shell:
gcloud auth list
- Aby sprawdzić, czy projekt jest skonfigurowany do użycia z gcloud, uruchom to polecenie:
gcloud config get project
- Sprawdź, czy projekt jest zgodny z oczekiwaniami, a następnie uruchom to polecenie, aby ustawić identyfikator projektu:
export PROJECT_ID=$(gcloud config get project)
3. Pobierz kod
Sklonuj repozytorium
- Sklonuj repozytorium do środowiska Cloud Shell:
git clone https://github.com/google/mcp.git
- Przejdź do katalogu z wersją demonstracyjną:
cd mcp/examples/launchmybakery
Uwierzytelnij się
Aby uwierzytelnić się na koncie Google Cloud, uruchom to polecenie. Jest to wymagane, aby ADK mogło uzyskać dostęp do BigQuery.
gcloud auth application-default login
Postępuj zgodnie z instrukcjami, aby dokończyć proces uwierzytelniania.
4. Konfigurowanie środowiska i BigQuery
Uruchom skrypty konfiguracji
- Uruchom skrypt konfiguracji środowiska. Ten skrypt włącza interfejsy BigQuery i interfejs API Map Google oraz tworzy plik
.envz identyfikatorem projektu i kluczem interfejsu API Map Google.
chmod +x setup/setup_env.sh
./setup/setup_env.sh
- Uruchom skrypt konfiguracji BigQuery. Ten skrypt automatyzuje tworzenie zasobnika Cloud Storage, przesyłanie danych oraz udostępnianie zbioru danych i tabel BigQuery.
chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh
Po zakończeniu działania skryptu powinien zostać utworzony zbiór danych mcp_bakery, który będzie zawierać te tabele:
- demographics – dane statystyczne i charakterystyka populacji według kodu pocztowego.
- bakery_prices – ceny konkurencji i szczegóły produktów różnych wypieków.
- sales_history_weekly – tygodniowe wyniki sprzedaży (ilość i przychody) według sklepu i produktu.
- foot_traffic – szacunkowe wyniki ruchu w sklepie stacjonarnym według kodu pocztowego i pory dnia.
- Aby sprawdzić, czy zbiór danych i tabele zostały utworzone, otwórz konsolę BigQuery w projekcie Google Cloud:
5. Zainstaluj ADK
Teraz, gdy infrastruktura jest gotowa, utwórzmy wirtualne środowisko Pythona i zainstalujmy wymagane pakiety dla ADK.
- Utwórz środowisko wirtualne:
python3 -m venv .venv
- Aktywuj środowisko wirtualne:
source .venv/bin/activate
- Zainstaluj ADK:
pip install "google-adk[mcp]"
- Przejdź do katalogu agenta:
cd adk_agent/
6. Sprawdzanie aplikacji ADK
W Cloud Shell kliknij przycisk Otwórz edytor , aby otworzyć edytor Cloud Shell i wyświetlić sklonowane repozytorium w katalogu mcp/examples/launchmybakery.
Kod agenta jest już dostępny w katalogu adk_agent/. Przyjrzyjmy się strukturze rozwiązania:
launchmybakery/
├── data/ # Pre-generated CSV files for BigQuery
├── adk_agent/ # AI Agent Application (ADK)
│ └── mcp_bakery_app/ # App directory
│ ├── agent.py # Agent definition
│ ├── tools.py # Custom tools for the agent
│ └── .env # Project configuration (created by setup script)
├── setup/ # Infrastructure setup scripts
└── cleanup/ # Infrastructure cleanup scripts
Najważniejsze pliki w mcp_bakery_app:
agent.py: podstawowa logika definiująca agenta, jego narzędzia i model (Gemini 3.5 Flash).tools.py: zawiera definicje narzędzi niestandardowych..env: zawiera konfigurację projektu i tajne dane (np. klucze interfejsu API) utworzone przez skrypt konfiguracji.
1. Inicjowanie zestawu narzędzi MCP:
Teraz otwórz w edytorze plik adk_agent/mcp_bakery_app/tools.py, aby dowiedzieć się, jak inicjowane są zestawy narzędzi MCP.
Aby umożliwić agentowi komunikację z BigQuery i Mapami Google, musimy skonfigurować klientów protokołu Model Context Protocol (MCP).
Kod ustanawia bezpieczne połączenia ze zdalnymi serwerami MCP Google za pomocą StreamableHTTPConnectionParams.
def get_maps_mcp_toolset():
dotenv.load_dotenv()
maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=MAPS_MCP_URL,
headers={
"X-Goog-Api-Key": maps_api_key
}
)
)
print("MCP Toolset configured for Streamable HTTP connection.")
return tools
def get_bigquery_mcp_toolset():
credentials, project_id = google.auth.default(
scopes=["https://www.googleapis.com/auth/bigquery"]
)
credentials.refresh(google.auth.transport.requests.Request())
oauth_token = credentials.token
HEADERS_WITH_OAUTH = {
"Authorization": f"Bearer {oauth_token}",
"x-goog-user-project": project_id
}
tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=BIGQUERY_MCP_URL,
headers=HEADERS_WITH_OAUTH
)
)
print("MCP Toolset configured for Streamable HTTP connection.")
return tools
- Zestaw narzędzi Map: konfiguruje połączenie z serwerem MCP Map za pomocą klucza interfejsu API.
- Zestaw narzędzi BigQuery: ta funkcja konfiguruje połączenie z serwerem MCP BigQuery. Używa google.auth do automatycznego pobierania danych uwierzytelniających Cloud, generuje token OAuth Bearer i wstawia go do nagłówka Authorization.
2. Definicja agenta:
Teraz otwórz w edytorze plik adk_agent/mcp_bakery_app/agent.py, aby zobaczyć, jak zdefiniowany jest agent.
Model LlmAgent jest inicjowany za pomocą modelu gemini-3.5-flash.
maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()
root_agent = LlmAgent(
model='gemini-3.5-flash',
name='root_agent',
instruction=f"""
Help the user answer questions by strategically combining insights from two sources:
1. **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the mcp_bakery dataset. Do not use any other dataset.
Run all query jobs from project id: {project_id}.
2. **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
Include a hyperlink to an interactive map in your response where appropriate.
""",
tools=[maps_toolset, bigquery_toolset]
)
- Instrukcje systemowe: agent otrzymuje konkretne instrukcje, aby łączyć dane z BigQuery (dane) i Map (analiza lokalizacji).
- Narzędzia: do agenta przypisane są zarówno
maps_toolset, jak ibigquery_toolset, co daje mu dostęp do funkcji obu usług.
Agent postępuje zgodnie z instrukcjami i narzędziami zdefiniowanymi w repozytorium. Możesz wprowadzać zmiany w instrukcjach, aby zobaczyć, jak wpływa to na zachowanie agenta.
7. Czat z agentem
Wróć do terminala w Cloud Shell i uruchom to polecenie, aby przejść do katalogu adk_agent (jeśli jeszcze tego nie zrobisz):
cd adk_agent/
Aby uruchomić interfejs internetowy ADK, uruchom to polecenie. To polecenie uruchamia lekki serwer WWW, który hostuje aplikację do czatu:
adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'
Po uruchomieniu serwera w Cloud Shell zobaczysz ten komunikat:
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Dostępne są 2 opcje dostępu do interfejsu ADK:
Opcja 1. Kliknij link lokalny Kliknij link http://127.0.0.1:8000, który pojawi się w terminalu Cloud Shell.
Opcja 2. Użyj podglądu w przeglądarce
- W prawym górnym rogu Cloud Shell kliknij przycisk Podgląd w przeglądarce.
- Kliknij Zmień port.
- Jako numer portu wpisz 8000 i kliknij Zmień i wyświetl podgląd.
Wejdź w interakcję z agentem , zadając te pytania w interfejsie internetowym. Powinny zostać wywołane odpowiednie narzędzia.
- Znajdź okolicę (makro): „Chcę otworzyć piekarnię w Los Angeles. Znajdź kod pocztowy z najwyższym wynikiem ruchu w sklepie stacjonarnym rano”.
Agent powinien używać narzędzi takich jak get_table_info i execute_sql, aby wysyłać zapytania do tabeli foot_traffic w BigQuery.
- Sprawdź lokalizację (mikro): „Czy możesz wyszukać „Piekarnie” w tym kodzie pocztowym, aby sprawdzić, czy rynek jest nasycony?”
Aby odpowiedzieć na to pytanie, agent powinien użyć narzędzi search places w zestawie narzędzi Map.
Spróbuj! Aby zobaczyć, jak działa agent ADK, zapoznaj się z tymi przykładowymi pytaniami:
- „Chcę otworzyć czwartą piekarnię w Los Angeles. Potrzebuję okolicy z dużą aktywnością rano. Znajdź kod pocztowy z najwyższym wynikiem ruchu w sklepie stacjonarnym „rano”.
- „Czy możesz wyszukać „Piekarnie” w tym kodzie pocztowym, aby sprawdzić, czy rynek jest nasycony? Jeśli jest ich zbyt wiele, sprawdź, czy w pobliżu są kawiarnie „Specialty Coffee”, abym mógł się w ich pobliżu ustawić i przyciągnąć ruch w sklepie stacjonarnym”.
- „Ok, chcę, aby była to marka premium. Jaka jest maksymalna cena za „Chleb na zakwasie” w aglomeracji Los Angeles?”
- „Teraz chcę prognozę przychodów na grudzień 2025 r. Sprawdź historię sprzedaży i pobierz dane z mojego najlepiej prosperującego sklepu dotyczące „Chleba na zakwasie”. Wykonaj prognozę na grudzień 2025 r., aby oszacować ilość, którą sprzedam. Następnie oblicz prognozowane łączne przychody, używając ceny premium, którą znaleźliśmy (użyjmy 18 USD)”.
- „To pokryje mój czynsz. Na koniec sprawdźmy logistykę. Znajdź najbliższy „Restaurant Depot” w proponowanym obszarze i upewnij się, że czas dojazdu nie przekracza 30 minut, aby móc codziennie uzupełniać zapasy”.
Gdy skończysz testowanie agenta, możesz zamknąć interfejs internetowy ADK, naciskając Ctrl+C w terminalu Cloud Shell.
8. Czyszczenie
Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tego ćwiczenia.
Uruchom skrypt czyszczenia. Ten skrypt usunie zbiór danych BigQuery, zasobnik Cloud Storage i klucze interfejsu API utworzone podczas konfiguracji.
chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh
9. Gratulacje
Misja zakończona! Udało Ci się utworzyć agenta do analizy lokalizacji za pomocą pakietu Agent Development Kit (ADK).
Dzięki połączeniu danych „firmowych” w BigQuery z kontekstem lokalizacji w świecie rzeczywistym z Map Google udało Ci się stworzyć zaawansowane narzędzie do złożonego wnioskowania biznesowego – wszystko to dzięki protokołowi Model Context Protocol (MCP) i Gemini.
Co udało Ci się osiągnąć:
- Infrastruktura jako kod: za pomocą narzędzi Google Cloud CLI udało Ci się udostępnić stos danych.
- Integracja z MCP: udało Ci się połączyć agenta AI z 2 różnymi zdalnymi serwerami MCP (BigQuery i Mapy) bez pisania złożonych otoczek interfejsu API.
- Ujednolicone rozumowanie: udało Ci się utworzyć jednego agenta, który potrafi strategicznie łączyć obserwacje z 2 różnych domen, aby rozwiązać problem biznesowy.
Dokumentacja
- Korzystanie z serwera MCP BigQuery
- Korzystanie z serwera MCP Groundling Lite w Mapach
- Zapoznaj się z materiałami edukacyjnymi, aby tworzyć i wdrażać agentów klasy korporacyjnej za pomocą Gemini Enterprise Agent Ready (GEAR).