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

1. Wprowadzenie

W tym module dowiesz się, jak utworzyć agenta za pomocą ADK, który jest oparty na Gemini 3.0 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 uzyskania danych demograficznych, cenowych i sprzedaży oraz do Map Google w celu analizowania i weryfikowania 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 musisz zrobić

Skonfiguruj dane: utwórz podstawowy zbiór danych piekarni w BigQuery.
Opracuj 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.
Analizuj rynek: 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.

Te warsztaty są przeznaczone dla deweloperów na wszystkich poziomach zaawansowania, w tym dla początkujących. Do tworzenia ADK będziesz używać interfejsu wiersza poleceń w Cloud Shell i kodu w języku Python. Nie musisz być ekspertem w zakresie Pythona, ale podstawowa wiedza o tym, jak czytać kod, pomoże Ci zrozumieć te koncepcje.

2. Zanim zaczniesz

Tworzenie projektu Google Cloud

W konsoli Google Cloud na stronie wyboru projektu wybierz lub utwórz projekt Google Cloud.

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.

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

Po połączeniu z Cloud Shell uruchom to polecenie, aby zweryfikować uwierzytelnianie w Cloud Shell:

gcloud auth list

Aby sprawdzić, czy projekt jest skonfigurowany do używania 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

Klonowanie repozytorium

Skopiuj repozytorium do środowiska Cloud Shell:

git clone https://github.com/google/mcp.git

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

Uruchom skrypt konfiguracji środowiska. Ten skrypt włącza interfejsy BigQuery i Google Maps API oraz tworzy plik .env z identyfikatorem projektu i kluczem interfejsu Maps API.

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:

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 (liczba i przychody) według sklepu i produktu.
foot_traffic – szacunkowe wyniki dotyczące ruchu pieszego według kodu pocztowego i pory dnia.

Sprawdź, czy zbiór danych i tabele zostały utworzone. W tym celu otwórz konsolę BigQuery w projekcie Google Cloud:

5. Instalowanie ADK

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

Utwórz środowisko wirtualne:

python3 -m venv .venv

Aktywuj środowisko wirtualne:

source .venv/bin/activate

Zainstaluj ADK:

pip install google-adk

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

Najważniejsze pliki w usłudze mcp_bakery_app:

agent.py: podstawowa logika definiująca agenta, jego narzędzia i model (Gemini 3.0 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 protokołu kontekstu modelu (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 Google: konfiguruje połączenie z serwerem MCP Map Google za pomocą klucza API.
Zestaw narzędzi BigQuery: ta funkcja konfiguruje połączenie z serwerem MCP BigQuery. 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-pro-preview.

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

root_agent = LlmAgent(
    model='gemini-3-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: agentowi przypisane są 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 uruchom to polecenie, aby przejść do katalogu adk_agent:

cd adk_agent

Aby uruchomić interfejs internetowy ADK, uruchom to polecenie. To polecenie uruchamia prosty serwer WWW, który będzie hostować aplikację do czatu:

adk web

Gdy serwer się uruchomi, możesz rozmawiać z agentem, klikając podany adres URL, aby uruchomić interfejs internetowy ADK.

Wejdź w interakcję z agentem, zadając mu poniższe pytania. Powinny się pojawić wywołania odpowiednich narzędzi.

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

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

Sprawdź lokalizację (mikro): „Czy możesz wyszukać „Piekarnie” w tym kodzie pocztowym, aby sprawdzić, czy jest tam duża konkurencja?”

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ę dzielnicy, w której wcześnie zaczyna się aktywność. Znajdź kod pocztowy z najwyższym wynikiem ruchu pieszego „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ąć klientów”.
„OK, chcę pozycjonować tę markę jako premium. Jaka jest maksymalna cena za „bochenek chleba na zakwasie” w aglomeracji Los Angeles?
„Teraz chcę prognozy 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 wystarczy na 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”.

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 Location Intelligence 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 wnioskowania biznesowego – wszystko to dzięki protokołowi kontekstu modelu (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: agent AI został połączony z 2 różnymi zdalnymi serwerami MCP (BigQuery i Mapy) bez konieczności pisania złożonych otoczek interfejsu API.
Ujednolicone wnioskowanie: utworzono pojedynczego agenta, który potrafi strategicznie łączyć statystyki z 2 różnych domen, aby rozwiązać problem biznesowy.