Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

1. Einführung

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

Der Agent orchestriert 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 den grundlegenden Bäckereidatensatz in BigQuery.
Agenten entwickeln:Erstellen Sie mit dem Agent Development Kit (ADK) einen intelligenten Agenten.
Tools einbinden:Statten Sie den Agenten über den MCP-Server mit BigQuery- und Maps-Funktionen aus.
Markt analysieren:Interagieren Sie mit dem Agenten, um Markttrends und -sä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 Anfänger. Sie verwenden die Befehlszeilenschnittstelle in Google Cloud Shell und Python-Code für die ADK-Entwicklung. Sie müssen kein Python-Experte sein, aber ein grundlegendes Verständnis des Lesens von Code 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

Die Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und in der die erforderlichen Tools vorinstalliert sind.

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

Führen Sie nach der Verbindung mit Cloud Shell diesen Befehl aus, um Ihre Authentifizierung in Cloud Shell zu überprüfen:

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

Bestätigen Sie, dass 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

Wechseln Sie zum Demoverzeichnis:

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

Setupskripts ausführen

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

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

Führen Sie das BigQuery-Setupskript aus. Mit diesem Skript werden das Erstellen des Cloud Storage-Buckets, das Hochladen von Daten und die Bereitstellung des BigQuery-Datasets und der Tabellen automatisiert.

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 sein:

demographics : Bevölkerungsdaten und -merkmale nach Postleitzahl
bakery_prices : Preise der Konkurrenz und Produktdetails 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 die Fußgängerfrequenz nach Postleitzahl und Tageszeit

Prüfen Sie, ob das Dataset und die Tabellen erstellt wurden, indem Sie in Ihrem Google Cloud-Projekt die BigQuery-Konsole aufrufen:

5. ADK installieren

Nachdem die Infrastruktur eingerichtet 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==1.28.0

Wechseln Sie zum Agentenverzeichnis:

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 Agentencode 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.1 Pro, Vorabversion) definiert.
tools.py: Enthält alle benutzerdefinierten Tooldefinitionen.
.env: Enthält Ihre Projektkonfiguration und Secrets (z. B. API-Schlüssel), die vom Setupskript erstellt wurden.

1. MCP-Toolset-Initialisierung:

Öffnen Sie jetzt 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: Diese Funktion konfiguriert die Verbindung zum BigQuery-MCP-Server. Dabei wird „google.auth“ verwendet, um Ihre Cloud-Anmeldedaten automatisch abzurufen, ein OAuth-Inhabertoken zu generieren und es in den Autorisierungsheader einzufügen.

2. Agentendefinition:

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

Der LlmAgent wird mit dem Modell gemini-3.1-pro-preview initialisiert.

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

Systemanweisungen:Der Agent erhält spezifische Anweisungen, um Erkenntnisse aus BigQuery (für Daten) und Maps (für die Standortanalyse) zu kombinieren.
Tools:Sowohl das maps_toolset als auch das bigquery_toolset werden dem Agenten 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 Agenten auswirkt.

7. Mit Ihrem Agenten chatten

Kehren Sie zum Terminal in Cloud Shell zurück und führen Sie diesen Befehl aus, um zum Verzeichnis adk_agent zu wechseln (falls noch nicht geschehen):

cd adk_agent/

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

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Sobald der Server gestartet ist, wird in Cloud Shell Folgendes angezeigt:

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

Sie haben zwei Möglichkeiten, auf die ADK-UI zuzugreifen:

Option 1: Auf den lokalen Link klicken Klicken Sie auf den Link http://127.0.0.1:8000, der in Ihrem Cloud Shell-Terminal angezeigt wird.

Option 2: Webvorschau verwenden

Klicken Sie rechts oben in Cloud Shell auf die Schaltfläche Webvorschau.
Wählen Sie Port ändern aus.
Geben Sie 8000 als Portnummer ein und klicken Sie auf Ändern und Vorschau.

Screenshot zum Öffnen der ADK-Benutzeroberfläche

Interagieren Sie mit dem Agenten , indem Sie in der Weboberfläche die folgenden Fragen stellen. Die entsprechenden Tools sollten aufgerufen werden.

Nachbarschaft finden (Makro) : „Ich möchte eine Bäckerei in Los Angeles eröffnen. Ermitteln Sie die Postleitzahl mit der höchsten Fußgängerfrequenz 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) : „Können Sie 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.

Jetzt sind Sie an der Reihe! Sehen Sie sich diese Beispielfragen an, um Ihren ADK-Agenten in Aktion zu sehen:

„Ich möchte meine vierte Bäckerei in Los Angeles eröffnen. Ich brauche eine Nachbarschaft mit viel Aktivität am Morgen. Ermitteln Sie die Postleitzahl mit der höchsten Fußgängerfrequenz am Morgen.“
„Können Sie in dieser Postleitzahl nach „Bäckereien“ suchen, um zu sehen, ob der Markt gesättigt ist? Wenn es zu viele gibt, suchen Sie nach „Spezialitätenkaffee“-Geschäften, damit ich mich in der Nähe positionieren kann, um von der Fußgängerfrequenz zu profitieren.“
„Okay, ich möchte das als Premiummarke positionieren. Was ist der Höchstpreis für ein „Sauerteigbrot“ im Großraum Los Angeles?“
„Jetzt möchte ich eine Umsatzprognose für Dezember 2025. Sehen Sie sich meine Verkaufshistorie an und verwenden Sie Daten aus meinem umsatzstärksten Geschäft für das „Sauerteigbrot“. Erstellen Sie eine Prognose für Dezember 2025, um die Menge zu schätzen, die ich verkaufen werde. Berechnen Sie dann den prognostizierten Gesamtumsatz mit einem Preis, der knapp unter dem von uns ermittelten Premiumpreis liegt (nehmen wir 18 $).“
„Damit kann ich meine Miete bezahlen. Sehen wir uns zum Schluss die Logistik an. Suchen Sie nach dem nächstgelegenen „Restaurant Depot“ zum vorgeschlagenen Gebiet und prüfen Sie, ob die Fahrtzeit für die tägliche Nachbestellung weniger als 30 Minuten beträgt.“

Wenn Sie mit dem Testen Ihres Agenten fertig sind, können Sie die ADK-Weboberfläche beenden, indem Sie in Ihrem Cloud Shell-Terminal Ctrl+C drücken.

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

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

Indem Sie die Lücke zwischen Ihren Unternehmensdaten in BigQuery und dem realen Standortkontext aus Google Maps geschlossen haben, haben Sie ein leistungsstarkes Tool für komplexe Geschäftsanalysen erstellt, das auf dem Model Context Protocol (MCP) und Gemini basiert.

Ergebnisse :

Infrastruktur als Code:Sie haben einen Datenstack 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 Analysen: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.