Tworzenie agenta ADK Location Intelligence z serwerami MCP na potrzeby BigQuery i Map Google

1. Wprowadzenie

W tym ćwiczeniu z programowania utworzysz agenta z użyciem pakietu ADK, który jest oparty na Gemini 3.1 Pro. 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 uzyskiwania danych demograficznych, cenowych i sprzedaży 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.

82dd7bd2823a821b.png

Co musisz zrobić

  • Skonfiguruj dane: utwórz podstawowy zbiór danych piekarni w BigQuery.
  • Tworzenie agenta: Utwórz inteligentnego agenta za pomocą pakietu Agent Development Kit (ADK).
  • Integracja narzędzi: wyposaż agenta w funkcje BigQuery i Map Google za pomocą serwera MCP.
  • Analiza rynku: wchodź w interakcje z agentem, aby ocenić trendy rynkowe i nasycenie rynku.

Czego potrzebujesz

  • przeglądarka, np. Chrome;
  • Projekt Google Cloud z włączonymi rozliczeniami lub konto Gmail.

To ćwiczenie jest przeznaczone dla deweloperów na wszystkich poziomach zaawansowania, w tym dla początkujących. Do tworzenia pakietu 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ć te koncepcje.

2. Zanim zaczniesz

Tworzenie projektu Google Cloud

  1. W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt w chmurze Google Cloud.

a3dd2e6dddc8f691.png

  1. Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.

Uruchamianie Cloud Shell

Cloud Shell to środowisko wiersza poleceń działające w Google Cloud, które zawiera niezbędne narzędzia.

  1. U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell:

404e4cce0f23e5c5.png

  1. Po połączeniu z Cloud Shell uruchom to polecenie, aby zweryfikować uwierzytelnianie w Cloud Shell:
gcloud auth list
  1. Aby sprawdzić, czy projekt jest skonfigurowany do używania z gcloud, uruchom to polecenie:
gcloud config get project
  1. 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

Klonowanie repozytorium

  1. Sklonuj repozytorium do środowiska Cloud Shell:
git clone https://github.com/google/mcp.git
  1. Przejdź do katalogu wersji demonstracyjnej:
cd mcp/examples/launchmybakery

Uwierzytelnianie

Uruchom to polecenie, aby uwierzytelnić się na koncie Google Cloud. Jest to wymagane, aby ADK miał dostęp do BigQuery.

gcloud auth application-default login

Postępuj zgodnie z instrukcjami, aby dokończyć proces uwierzytelniania.

4. Konfigurowanie środowiska i BigQuery

Uruchamianie skryptów konfiguracji

  1. Uruchom skrypt konfiguracji środowiska. Ten skrypt włącza interfejsy BigQuery i interfejs API Map Google oraz tworzy plik .env z identyfikatorem projektu i kluczem interfejsu API Map Google.
chmod +x setup/setup_env.sh
./setup/setup_env.sh
  1. 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 mcp_bakeryzbiór danych, który będzie zawierać te tabele:

  • dane demograficzne – 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 dotyczące ruchu w sklepie stacjonarnym według kodu pocztowego i pory dnia.
  1. Sprawdź, czy zbiór danych i tabele zostały utworzone. W tym celu otwórz konsolę BigQuery w projekcie Google Cloud:

6bd0a0cd7522dd11.jpeg

5. Instalowanie ADK

Infrastruktura jest już gotowa, więc utwórzmy wirtualne środowisko Pythona i zainstalujmy wymagane pakiety ADK.

  1. Utwórz środowisko wirtualne:
python3 -m venv .venv
  1. Aktywuj środowisko wirtualne:
source .venv/bin/activate
  1. Zainstaluj ADK:
pip install google-adk==1.28.0
  1. 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.

a940b7eaf3c9f4b3.png

Kod agenta jest już podany 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

Kluczowe pliki w usłudze mcp_bakery_app:

  • agent.py: podstawowa logika definiująca agenta, jego narzędzia i model (Gemini 3.1 Pro w wersji testowej).
  • tools.py: zawiera definicje narzędzi niestandardowych.
  • .env: zawiera konfigurację projektu i tajne klucze (np. klucze interfejsu API) utworzone przez skrypt konfiguracji.

1. Inicjowanie zestawu narzędzi MCP:

Teraz otwórz adk_agent/mcp_bakery_app/tools.py w edytorze, aby dowiedzieć się, jak inicjowane są zestawy narzędzi MCP.

Aby umożliwić naszemu agentowi komunikację z BigQuery i Mapami Google, musimy skonfigurować klientów Model Context Protocol (MCP).

Kod nawiązuje bezpieczne połączenia ze zdalnymi serwerami MCP Google za pomocą parametru 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 API.
  • Zestaw narzędzi BigQuery: ta funkcja konfiguruje połączenie z serwerem BigQuery MCP. Używa biblioteki google.auth do automatycznego pobierania danych logowania w Cloud, generowania tokena OAuth Bearer i wstrzykiwania go do nagłówka Authorization.

2. Definicja agenta:

Teraz otwórz adk_agent/mcp_bakery_app/agent.py w edytorze, aby zobaczyć, jak zdefiniowany jest agent.

LlmAgent jest inicjowany za pomocą modelu gemini-3.1-pro-preview.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3.1-pro-preview',
    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 szczegółowe instrukcje dotyczące łączenia statystyk z BigQuery (dane) i Map Google (analiza lokalizacji).
  • Narzędzia: agent ma przypisane zarówno maps_toolset, jak i bigquery_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 sprawdzić, jak wpływają one na zachowanie agenta.

7. Czatuj z agentem.

Wróć do terminala w Cloud Shell i wykonaj to polecenie, aby przejść do katalogu adk_agent (jeśli jeszcze tego nie zrobisz):

cd adk_agent/

Aby uruchomić interfejs internetowy pakietu ADK, uruchom to polecenie: To polecenie uruchamia lekki serwer WWW, który będzie hostować 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ęp do interfejsu ADK możesz uzyskać na 2 sposoby:

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 internecie

  1. W prawym górnym rogu Cloud Shell kliknij przycisk Podgląd w przeglądarce.
  2. Kliknij Zmień port.
  3. Wpisz 8000 jako numer portu i kliknij Zmień i wyświetl podgląd.

Zrzut ekranu pokazujący, jak otworzyć interfejs ADK

Wejdź w interakcję z Agentem, zadając w interfejsie internetowym te pytania: Powinny się pojawić odpowiednie narzędzia.

  1. Znajdź okolicę (makro): „Chcę otworzyć piekarnię w Los Angeles. Znajdź kod pocztowy z najwyższym wynikiem ruchu w sklepie stacjonarnym rano”.

5f2a48bebfc49709.png

Agent powinien używać narzędzi get_table_info i execute_sql do wykonywania zapytań w tabeli foot_traffic w BigQuery.

  1. Sprawdź lokalizację (mikro): „Czy możesz wyszukać „Piekarnie” w tym kodzie pocztowym, aby sprawdzić, czy jest on nasycony?”

32796c9a8cefca7.png

Aby odpowiedzieć na to pytanie, agent powinien użyć search places narzędzi z zestawu narzędzi Map Google.

Wypróbuj tę funkcję Aby zobaczyć, jak działa agent ADK, zapoznaj się z tymi przykładowymi pytaniami:

  • „Chcę otworzyć czwartą piekarnię w Los Angeles. Potrzebuję okolicy, w której wcześnie zaczyna się aktywność. 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 specjalistyczne, abym mógł się w ich pobliżu ustawić i przyciągnąć ruch w sklepie stacjonarnym”.
  • „OK, chcę pozycjonować tę markę jako premium. Jaka jest maksymalna cena za „bochenek na zakwasie” w aglomeracji Los Angeles?
  • „Chcę teraz prognozę przychodów na grudzień 2025 r. Sprawdź moją historię sprzedaży i pobierz dane z najlepiej działającego sklepu w przypadku „Chleba na zakwasie”. Wykonaj prognozę na grudzień 2025 r., aby oszacować liczbę sprzedanych produktów. Następnie oblicz przewidywane łączne przychody, używając ceny nieco niższej od znalezionej ceny premium (załóżmy, że będzie to 18 USD).
  • „To pokryje mój czynsz. Na koniec sprawdźmy logistykę. Znajdź najbliższy „Restaurant Depot” w proponowanej okolicy i upewnij się, że czas dojazdu nie przekracza 30 minut w przypadku codziennego uzupełniania zapasów”.

Gdy skończysz testowanie agenta, możesz zamknąć interfejs internetowy ADK, naciskając klawisz Ctrl+C w terminalu Cloud Shell.

8. Czyszczenie

Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tego Codelabu.

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 ukoń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 powstało zaawansowane narzędzie do złożonego rozumowania biznesowego, które wykorzystuje Model Context Protocol (MCP) i Gemini.

Co udało Ci się osiągnąć:

  • Infrastruktura jako kod: stos danych został przez Ciebie udostępniony za pomocą narzędzi Google Cloud CLI.
  • Integracja z MCP: agenta AI połączono z 2 różnymi zdalnymi serwerami MCP (BigQuery i Mapy) bez konieczności pisania złożonych otoczek interfejsu API.
  • Ujednolicone rozumowanie: utworzono pojedynczego agenta, który potrafi strategicznie łączyć statystyki z 2 różnych dziedzin, aby rozwiązać problem biznesowy.

Dokumentacja