Location Intelligence ADK-Agent mit MCP-Servern für BigQuery und Google Maps erstellen

1. Einführung

In diesem Codelab erstellen Sie einen Agenten mit dem ADK, der auf Gemini 3.0 Pro basiert. Der Agent wird mit Tools von zwei Remote-MCP-Servern (von Google gehostet) ausgestattet, um sicher auf BigQuery für demografische Daten, Preis- und Verkaufsdaten und auf Google Maps für die Analyse und Validierung von realen Standorten zuzugreifen.

Der Agent koordiniert Anfragen zwischen dem Nutzer und Google Cloud-Diensten, um Geschäftsprobleme im Zusammenhang mit dem fiktiven Bäckereidatensatz zu lösen.

Aufgaben

Daten einrichten:Erstellen Sie das grundlegende Bäckerei-Dataset in BigQuery.
Agent entwickeln:Erstellen Sie mit dem Agent Development Kit (ADK) einen intelligenten Agenten.
Tools einbinden:Stellen Sie dem Agent über den MCP-Server BigQuery- und Maps-Funktionen zur Verfügung.
Markt analysieren:Interagieren Sie mit dem Agent, um Markttrends und die Marktsättigung zu bewerten.

Voraussetzungen

Ein Webbrowser wie Chrome
Ein Google Cloud-Projekt mit aktivierter Abrechnung oder ein Gmail-Konto.

Dieses Codelab richtet sich an Entwickler aller Erfahrungsstufen, auch an Anfänger. Sie verwenden die Befehlszeile in Google Cloud Shell und Python-Code für die ADK-Entwicklung. Sie müssen kein Python-Experte sein, aber ein grundlegendes Verständnis dafür, wie man Code liest, hilft Ihnen, die Konzepte zu verstehen.

2. Hinweis

Google Cloud-Projekt erstellen

Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Cloud Shell starten

Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und mit den erforderlichen Tools vorinstalliert ist.

Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren:

Sobald Sie mit Cloud Shell verbunden sind, führen Sie diesen Befehl aus, um Ihre Authentifizierung in Cloud Shell zu bestätigen:

gcloud auth list

Führen Sie den folgenden Befehl aus, um zu bestätigen, dass Ihr Projekt für die Verwendung mit gcloud konfiguriert ist:

gcloud config get project

Prüfen Sie, ob das Projekt wie erwartet ist, und führen Sie dann den folgenden Befehl aus, um Ihre Projekt-ID festzulegen:

export PROJECT_ID=$(gcloud config get project)

3. Code abrufen

Repository klonen

Klonen Sie das Repository in Ihre Cloud Shell-Umgebung:

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

Rufen Sie das Demoverzeichnis auf:

cd mcp/examples/launchmybakery

Authentifizieren

Führen Sie den folgenden Befehl aus, um sich bei Ihrem Google Cloud-Konto zu authentifizieren. Dies ist erforderlich, damit das ADK auf BigQuery zugreifen kann.

gcloud auth application-default login

Folgen Sie der Anleitung, um die Authentifizierung abzuschließen.

4. Umgebung und BigQuery konfigurieren

Einrichtungsskripts ausführen

Führen Sie das Skript zur Einrichtung der Umgebung aus. Mit diesem Skript werden die BigQuery- und Google Maps-APIs aktiviert und eine .env-Datei mit Ihrer Projekt-ID und Ihrem Maps API-Schlüssel erstellt.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

Führen Sie das BigQuery-Einrichtungsskript aus. Dieses Script automatisiert das Erstellen des Cloud Storage-Buckets, das Hochladen von Daten und das Bereitstellen des BigQuery-Datasets und der Tabellen.

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

Nach Abschluss des Skripts sollte das Dataset mcp_bakery erstellt und mit den folgenden Tabellen gefüllt werden:

Demografische Merkmale: Volkszählungsdaten und Bevölkerungsmerkmale nach Postleitzahl.
bakery_prices: Preise und Produktdetails von Mitbewerbern für verschiedene Backwaren.
sales_history_weekly: wöchentliche Verkaufsleistung (Menge und Umsatz) nach Geschäft und Produkt.
foot_traffic: Geschätzte Werte für Ladenbesuche nach Postleitzahl und Tageszeit.

Prüfen Sie, ob das Dataset und die Tabellen erstellt wurden. Rufen Sie dazu in Ihrem Google Cloud-Projekt die BigQuery Console auf:

5. ADK installieren

Nachdem die Infrastruktur bereit ist, erstellen wir eine virtuelle Python-Umgebung und installieren die erforderlichen Pakete für das ADK.

Virtuelle Umgebung erstellen:

python3 -m venv .venv

Aktivieren Sie die virtuelle Umgebung:

source .venv/bin/activate

Installieren Sie das ADK:

pip install google-adk

Rufen Sie das Agent-Verzeichnis auf:

cd adk_agent/

6. ADK-Anwendung prüfen

Klicken Sie in Cloud Shell auf die Schaltfläche Editor öffnen, um den Cloud Shell-Editor zu öffnen und das geklonte Repository im Verzeichnis mcp/examples/launchmybakery aufzurufen.

Der Agent-Code ist bereits im Verzeichnis adk_agent/ enthalten. Sehen wir uns die Lösungsstruktur an:

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

Wichtige Dateien in mcp_bakery_app:

agent.py: Die Kernlogik, die den Agenten, seine Tools und das Modell (Gemini 3.0 Pro-Vorschau) definiert.
tools.py: Enthält alle benutzerdefinierten Tooldefinitionen.
.env: Enthält Ihre Projektkonfiguration und Geheimnisse (z. B. API-Schlüssel), die vom Einrichtungs-Script erstellt wurden.

1. Initialisierung des MCP-Toolsets:

Öffnen Sie nun adk_agent/mcp_bakery_app/tools.py im Editor, um zu sehen, wie die MCP-Toolsets initialisiert werden.

Damit unser Agent mit BigQuery und Google Maps kommunizieren kann, müssen wir die MCP-Clients (Model Context Protocol) konfigurieren.

Der Code stellt mit StreamableHTTPConnectionParams sichere Verbindungen zu den Remote-MCP-Servern von Google her.

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

Maps Toolset:Konfiguriert die Verbindung zum Maps MCP-Server mit Ihrem API-Schlüssel.
BigQuery-Toolset:Mit dieser Funktion wird die Verbindung zum BigQuery MCP-Server konfiguriert. Dabei wird „google.auth“ verwendet, um Ihre Cloud-Anmeldedaten automatisch abzurufen, ein OAuth-Bearer-Token zu generieren und in den Autorisierungsheader einzufügen.

2. Agent-Definition:

Öffnen Sie nun adk_agent/mcp_bakery_app/agent.py im Editor, um zu sehen, wie der Agent definiert ist.

LlmAgent wird mit dem Modell gemini-3-pro-preview initialisiert.

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]
)

Systemanweisungen:Der Agent erhält spezifische Anweisungen, um Statistiken aus BigQuery (für Daten) und Maps (für Standortanalysen) zu kombinieren.
Tools:Sowohl maps_toolset als auch bigquery_toolset sind dem Agent zugewiesen, sodass er auf die Funktionen beider Dienste zugreifen kann.

Der Agent hält sich an die im Repository definierten Anweisungen und Tools. Sie können die Anweisungen ändern, um zu sehen, wie sich das auf das Verhalten des Agents auswirkt.

7. Chatten Sie mit Ihrem Agent.

Kehren Sie zum Terminal in Cloud Shell zurück und führen Sie diesen Befehl aus, um das Verzeichnis adk_agent zu öffnen:

cd adk_agent

Führen Sie den folgenden Befehl aus, um die ADK-Weboberfläche zu starten. Mit diesem Befehl wird ein einfacher Webserver zum Hosten der Chatanwendung gestartet:

adk web

Sobald der Server gestartet wurde, können Sie mit Ihrem Agent chatten. Klicken Sie dazu auf die bereitgestellte URL, um die ADK-Weboberfläche zu starten.

Interagieren Sie mit dem KI-Agenten, indem Sie die folgenden Fragen stellen. Sie sollten sehen, dass die entsprechenden Tools aufgerufen werden.

Find the Neighborhood (Macro) (Finde das Viertel (Makro)): „Ich möchte eine Bäckerei in Los Angeles eröffnen. Finde die Postleitzahl mit dem höchsten Wert für die Anzahl der Besucher am Morgen.“

Der Agent sollte Tools wie get_table_info und execute_sql verwenden, um die Tabelle „foot_traffic“ in BigQuery abzufragen.

Standort validieren (Mikro): „Kannst du in dieser Postleitzahl nach ‚Bäckereien‘ suchen, um zu sehen, ob der Markt gesättigt ist?“

Der Agent sollte die search places-Tools im Maps-Toolset verwenden, um diese Frage zu beantworten.

Probieren Sie es aus! Hier sind einige Beispielfragen, mit denen Sie Ihren ADK-Agenten in Aktion sehen können:

„Ich möchte meine vierte Bäckerei in Los Angeles eröffnen. Ich brauche ein Viertel, in dem früh etwas los ist. Finde die Postleitzahl mit dem höchsten Wert für die Besucherzahlen am Morgen.“
„Kannst du in dieser Postleitzahl nach ‚Bäckereien‘ suchen, um zu sehen, ob der Markt gesättigt ist? Wenn es zu viele sind, suche nach Fachgeschäften für Kaffeespezialitäten, damit ich mich in der Nähe positionieren kann, um Laufkundschaft zu gewinnen.“
„Okay, und ich möchte das als Premiummarke positionieren. Was ist der Höchstpreis, der für ein „Sauerteigbrot“ im Großraum Los Angeles berechnet wird?“
„Jetzt möchte ich eine Umsatzprognose für Dezember 2025. Sieh dir meinen Verkaufsverlauf an und verwende Daten aus meinem umsatzstärksten Geschäft für das Produkt „Sauerteigbrot“. Erstelle eine Prognose für Dezember 2025, um die voraussichtliche Verkaufsmenge zu schätzen. Berechne dann den prognostizierten Gesamtumsatz mit dem von uns ermittelten Premium-Preis (nehmen wir 18 $)“
„Damit kann ich meine Miete bezahlen. Sehen wir uns zum Schluss noch die Logistik an. Finde das nächste „Restaurant Depot“ in der Nähe des vorgeschlagenen Gebiets und sorge dafür, dass die Fahrzeit für die tägliche Wiederauffüllung weniger als 30 Minuten beträgt.“

8. Bereinigen

Löschen Sie die in diesem Codelab erstellten Ressourcen, um laufende Gebühren für Ihr Google Cloud-Konto zu vermeiden.

Führen Sie das Bereinigungsskript aus. Mit diesem Script werden das BigQuery-Dataset, der Cloud Storage-Bucket und die bei der Einrichtung erstellten API-Schlüssel gelöscht.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. Glückwunsch

Mission abgeschlossen! Sie haben mit dem Agent Development Kit (ADK) einen Location Intelligence-Agenten erstellt.

Durch die Überbrückung der Lücke zwischen Ihren Unternehmensdaten in BigQuery und dem realen Standortkontext von Google Maps haben Sie ein leistungsstarkes Tool für komplexe geschäftliche Entscheidungen geschaffen, das auf dem Model Context Protocol (MCP) und Gemini basiert.

Was Sie erreicht haben:

Infrastructure as Code:Sie haben einen Daten-Stack mit Google Cloud CLI-Tools bereitgestellt.
MCP-Integration:Sie haben einen KI-Agenten mit zwei verschiedenen Remote-MCP-Servern (BigQuery und Maps) verbunden, ohne komplexe API-Wrapper schreiben zu müssen.
Einheitliche Argumentation:Sie haben einen einzelnen Agenten erstellt, der in der Lage ist, Erkenntnisse aus zwei verschiedenen Bereichen strategisch zu kombinieren, um ein Geschäftsproblem zu lösen.