Google ADK‑tutorial: een MCP‑serverlogistiekagent bouwen

De grootste hobbel bij het bouwen van geavanceerde AI‑agents zit tegenwoordig niet in het model, maar in de integratie. Als je een agent toegang wilt geven tot tien verschillende enterprise‑tools, moet je meestal tien verschillende API‑wrappers schrijven. Uit mijn ervaring leidt dit tot wrapper‑moeheid en een enorme onderhoudslast. Elke keer dat een API verandert, gaat je agent stuk.

De oplossing zit in de samenwerking tussen de Google Agent Development Kit (ADK) en het Model Context Protocol (MCP). Als we de AI zien als een medewerker, dan is de ADK het "brein" (die logica en geheugen orkestreert), terwijl MCP de "handen" vertegenwoordigt (een gestandaardiseerde manier om elke tool op te pakken en te gebruiken).

In deze tutorial bouwen we met ADK een echte logistieke recovery‑agent. De agent zal:

1. BigQuery bevragen op vertraagde orders met hoge prioriteit. 
2. De daadwerkelijke rijafstand van het magazijn naar de klant berekenen met de Google Maps MCP‑server. 
3. Een herstelactie aanbevelen, zoals upgraden naar luchtvervoer voor langeafstandsverzendingen.

Dit alles gebeurt zonder een regel aangepaste API‑code te schrijven. De agent ontdekt en gebruikt de tools automatisch.

Nieuw bij Google Cloud? Ik raad aan te beginnen met de gratis cursus Introduction to GCP om billing, projecten en basisdiensten te behandelen.

Wat is de Google ADK?

De Google Agent Development Kit (ADK) is Googles open‑source, code‑first framework voor het bouwen, testen en uitrollen van AI‑agents. Terwijl frameworks zoals LangChain zich richten op chains, is ADK gebouwd voor uitvoering. Het biedt een gestandaardiseerde structuur voor hoe agents denken, toolsets gebruiken en draaien in productieomgevingen.

Dit zijn de kernconcepten:

• Agents: De kernentiteit, gedefinieerd door het model (bijv. Gemini 2.0 Flash) en de specifieke set instructies.
• Toolsets: Een verzameling capabilities. In plaats van tools handmatig te definiëren, wijzen we de ADK naar een MCP‑server, en die "leert" de tools automatisch.
• Runners: De uitvoeringsmotor die de conversatiestatus en de iteratieve "thought‑action‑observation"‑loop beheert.

Met deze code‑first aanpak kunnen we versiebeheer, testen en CI/CD inzetten zoals bij reguliere software. Het biedt ook diepe Google‑integratie, wat betekent dat beheerde MCP‑servers voor BigQuery of Maps bijna geen deployment vereisen.

Voor een vergelijking van de "grote drie" cloudproviders en hun diensten, bekijk zeker onze gids over AWS vs. Azure vs. Google Cloud.

Architectuur en logicaflow van Google ADK‑integratie

Onze logistieke recovery‑agent volgt een duidelijke redeneringsroute om een bedrijfsprobleem op te lossen. Het begrijpen van de flow helpt als je later de promptinstructies gaat schrijven.

De redeneercyclus volgt deze stappen:

1. De agent roept de BigQuery MCP aan om rijen te vinden waar status='Delayed' en priority='High'. 

2. Voor elke geretourneerde order haalt de agent de magazijn- en klantadressen op. 

3. De agent roept voor elke order de Google Maps MCP aan om de rijafstand te berekenen. 

4. De agent past bedrijfslogica toe (bijv. een afstand van meer dan 500 mijl betekent luchtvervoer) en presenteert een markdown‑tabel met aanbevelingen.

De MCP‑servers instellen

Voordat we kunnen gaan coderen, moeten we de onderliggende cloudinfrastructuur voorbereiden en de MCP‑servers gereedmaken. Uit mijn ervaring is het juist instellen van IAM‑machtigingen het belangrijkste onderdeel van deze fase.

Stap 1: Google Cloud CLI initialiseren 

Zorg dat je eerst de Google Cloud CLI hebt geïnstalleerd. Open je terminal en voer de volgende opdracht uit om je lokale omgeving aan je Google‑account te koppelen:

gcloud init

Zodra je dit uitvoert, opent automatisch een browservenster. Je wordt gevraagd in te loggen met je Google‑account. Na het inloggen klik je op Allow om de CLI toestemming te geven om je resources te beheren. 

Terug in je terminal vraagt de prompt je om een standaardproject te selecteren. Als je er al een hebt gemaakt, kies dan de ID van het project, of maak een nieuw project aan in de terminal.

Stap 2: Facturering instellen

Om de API‑services te gebruiken, moet je facturering instellen. Dat gezegd hebbende: Google Cloud geeft je $300 aan gratis tegoed voor 90 dagen om diensten zoals Compute, GKE en Maps uit te proberen, en die gratis tegoeden zijn ruim voldoende voor het voorbeeld in deze tutorial. Je betaalt pas als je pay‑as‑you‑go inschakelt of vooraf betaalt. Zo stel je facturering in:

1. Ga naar de Google Console‑factureringspagina en log in met het account dat je voor gcloud gebruikt.

2. Maak een factureringsaccount aan als je er nog geen hebt (het toevoegen van een betaalmethode is vereist, maar gratis tegoed wordt eerst toegepast).

3. Koppel het factureringsaccount aan je project: Billing → Link a project → selecteer je project, of voer uit:

gcloud billing projects link YOUR_PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

Stap 3: Kern‑API's en MCP‑services inschakelen

Vervolgens moeten we de primaire product‑API's inschakelen. Hiermee kan de agent de ruwe dataservices zoals BigQuery en Maps bereiken.

gcloud services enable bigquery.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable mapstools.googleapis.com

Nu moeten we de Managed MCP Endpoints inschakelen. Ik vond het nuttig om deze te zien als de vertaler‑interfaces die boven op de reguliere API's zitten. 

Laten we eerst je project‑ID en account‑e-mailadres opslaan in omgevingsvariabelen. Zo hoeven we ze niet bij elk volgend commando handmatig te typen:

export PROJECT_ID=$(gcloud config get-value project)
export USER_EMAIL=$(gcloud config get-value account)

Met die variabelen ingesteld, voer je de volgende opdrachten uit om de bètaversie van MCP‑features voor je specifieke project in te schakelen. Deze opdrachten vragen Google om de externe MCP‑endpoints voor je agent voor te bereiden:

gcloud beta services mcp enable bigquery.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable mapstools.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable container.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable compute.googleapis.com --project=$PROJECT_ID

Stap 3: IAM en Maps‑sleutels configureren 

MCP gebruikt een "dubbel‑laag" beveiligingsmodel. Je hebt toestemming nodig om met de MCP‑server zelf te praten en aparte toestemming om toegang te krijgen tot de daadwerkelijke data (zoals rijen in een tabel). Je kunt dit doen met de gcloud‑CLI of de Google Cloud Console‑UI.

IAM optie A: met de gcloud‑CLI 

Om je account toestemming te geven om MCP te gebruiken en met BigQuery te werken, voer je deze drie opdrachten uit:

# Permission to talk to the MCP Translator
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/mcp.toolUser"

# Permissions to run BigQuery jobs and view data
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.jobUser"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.dataViewer"

IAM optie B: met de Google Cloud Console (UI)

Als je liever een visuele interface gebruikt, kun je deze stappen in de browser volgen:

1. Ga naar de pagina IAM & Admin in je Google Cloud Console.
2. Zoek je e‑mailadres in de lijst en klik op het pictogram Edit Member (potlood).
3. Klik op Add Another Role en zoek op MCP Tool User.
4. Herhaal dit om BigQuery Data Viewer en BigQuery Job User toe te voegen.
5. Klik op Save.

Maak een Maps API‑sleutel

Maak tot slot een Maps API‑sleutel. In tegenstelling tot BigQuery, dat je inloggegevens gebruikt, gebruikt de Maps MCP‑server deze sleutel voor facturering en quotabeheer: 

gcloud alpha services api-keys create --display-name="Maps-MCP-Key"

Stap 4: Servers lokaal valideren met MCP Inspector

Voordat we onze Python‑code schrijven, doen we een sanity check met de MCP Inspector. We gebruiken het npx‑commando, een tool die bij Node.js hoort. 

Het doel is een package (zoals de inspector) direct te draaien zonder het permanent op je computer te installeren. Voer dit uit in je terminal:

npx @modelcontextprotocol/inspector

Dit start een webinterface in je browser (meestal op http://localhost:3000). Ik heb in de onderstaande setuplist specifieke keuzes gemaakt om zeker te weten dat we de Remote Managed‑versie van Googles servers testen, niet een lokale mock:

1. Transport type: Streamable HTTP. We kiezen dit omdat het het productie‑standaardprotocol is dat Google gebruikt voor beheerde cloudservers.

2. URL: Voer https://mapstools.googleapis.com/mcp in. Dit is de directe voordeur naar Googles Maps MCP.

3. Connection Type: via Proxy. Dit is een cruciale keuze. Door "Proxy" te selecteren, gebruikt de inspector je lokale gcloud‑login om alle complexe beveiligingshandshakes automatisch af te handelen.

4. Custom Headers: Voeg X‑Goog‑Api‑Key toe en plak je sleutel van Stap 3.

5. Klik op Connect.

Je zou nu een groene Connected‑status moeten zien. Klik op de knop List Tools om een lijst te zien van alle mogelijkheden die de server biedt. Als je compute_routes in die lijst ziet, is je infrastructuur perfect geconfigureerd.

Wil je dieper begrijpen hoe je BigQuery, Maps en andere Google‑diensten voor je agents gebruikt? Bekijk dan zeker deze tutorial over Google MCP‑servers.

Een MCP‑serveragent bouwen met de Google ADK

Met de infrastructuur gereed, gaan we nu naar onze lokale ontwikkelomgeving. We beginnen met het organiseren van onze projectbestanden.

Stap 1: Projectstructuur en afhankelijkheden instellen

Maak om te beginnen een map voor je project en zet een virtuele omgeving op.

mkdir my-agents
cd my-agents
python -m venv .venv
source .venv/bin/activate

Het laatste commando hierboven is voor macOS of Linux; gebruik op Windows in plaats daarvan .venv\Scripts\activate.

Installeer daarna het pakket google-adk samen met de ondersteunende libraries.

pip install google-adk google-generativeai python-dotenv httpx  google-auth

Maak nog een .env-bestand in je hoofdmap om je PROJECT_ID en de MAPS_API_KEY die je in de vorige stap hebt gegenereerd, op te slaan.

Stap 2: De MCP‑toolsets configureren

In een script met de naam tools.py schrijven we geen code om "data op te halen". In plaats daarvan schrijven we code om verbinding te maken met een server die weet hoe hij data ophaalt. 

Ik heb gemerkt dat het scheiden van de tools en de logica het project veel eenvoudiger maakt om te debuggen. Omdat we praten met externe Google Cloud‑endpoints, gebruiken we StreamableHTTPConnectionParams om de authenticatieheaders af te handelen.

import os
import google.auth
import google.auth.transport.requests
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams 

# --- BigQuery Toolset ---
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())
        
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://bigquery.googleapis.com/mcp",
            headers={
                "Authorization": f"Bearer {credentials.token}",
                # 'x-goog-user-project' is vital for BigQuery billing
                "x-goog-user-project": project_id,
                "Content-Type": "application/json"
            }
        )
    )

# --- Maps Toolset ---
def get_maps_mcp_toolset():
    maps_api_key = os.getenv('MAPS_API_KEY')
    
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://mapstools.googleapis.com/mcp",
            headers={
                "X-Goog-Api-Key": maps_api_key,
                "Content-Type": "application/json"
            }
        )
    )

Stap 3: De missie van de agent definiëren

Nu bouwen we het "brein". Uit mijn ervaring is een van de Gemini Flash‑modellen hier de beste keuze, omdat ze razendsnel zijn in tool‑calls. 

We geven de agent een standaard werkwijze via de instructies in het bestand agent.py. Let op hoe we een duidelijke pijplijn van vier stappen gebruiken om te voorkomen dat de agent in de war raakt.

from .tools import get_maps_mcp_toolset, get_bigquery_mcp_toolset
from google.adk.agents import LlmAgent

# We're giving the agent a very structured 'Instruction' set. 
# Think of this as the SOP (Standard Operating Procedure) for your agent.
root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='logistics_recovery_agent',
    instruction="""
      You are an expert Retail Operations Recovery Agent. 
      Your job is to find high-priority problems and solve them using the tools provided.

      Step 1: Use 'execute_sql' to find orders where status is 'Delayed' and priority is 'High'.
      Step 2: For every result, pull the warehouse and customer addresses.
      Step 3: Call the Maps 'compute_routes' tool to find the exact drive distance.
      Step 4: Use this logic: If distance > 500 miles, recommend 'Air Shipping'. 
            Otherwise, recommend 'Regional Express Ground'.
    
      Output the final result as a clean Markdown table.
    """,
    # We simply drop our toolsets here. 
    # ADK handles the complexity of deciding which tool to call when.
    tools=[get_maps_mcp_toolset(), get_bigquery_mcp_toolset()]
)

Stap 4: De agent‑loop draaien 

Om de agent te draaien gebruiken we de runner. Deze component houdt de conversatiestatus bij, zodat de agent weet wat hij al heeft gedaan en wat de volgende stap is.

from google.adk.runners import Runner
from google.genai import types

async def main():
    # The Runner acts as the host for our agent.
    runner = Runner(app_name="logistics_app", agent=root_agent)

    # Wrap the user input in the standard GenAI Content format
    user_input = "Identify high-priority delayed orders and suggest recovery shipping methods."
    content = types.Content(role="user", parts=[types.Part(text=user_input)])

    print("--- Starting Smart Logistics Agent ---")
    
    # We use run_async to stream the 'events' (Thoughts and Tool Calls)
    async for event in runner.run_async(user_id="admin_user", new_message=content):
        # We only want to print the text part of the response to the console
        if hasattr(event, 'content') and event.content.parts:
            print(event.content.parts[0].text)

Wat gebeurt er achter de schermen?

Wanneer je runner.run_async aanroept, start de ADK een iteratieve lus:

1. Gemini denkt: "Ik moet eerst de vertraagde orders zien."

2. ADK handelt: het roept de tool execute_sql aan vanuit je BigQuery MCP‑toolset.

3. Observatie: de tool retourneert de orderdata.

4. Gemini denkt: "Nu heb ik afstanden nodig voor deze twee orders."

5. ADK handelt: het roept twee keer de Maps MCP‑tool aan.

6. Definitief antwoord: Gemini ziet alle data, past je "500‑mijl"‑logica toe en formatteert de tabel.

Onze Google ADK‑agent testen in de webconsole

Hoewel de terminal geweldig is voor logs, bevat ADK een ingebouwde webconsole die het interne redeneren van de agent visualiseert. Ik vond dit het meest behulpzame hulpmiddel voor debugging.

Start de interface met adk web. Zodra de server draait, open je je browser op http://127.0.0.1:8000. Je ziet een schone, chatachtige interface waar je de opdracht kunt sturen: "Identify high-priority delayed orders and suggest recovery shipping methods."

De uitvoeringstrace analyseren

De ADK‑console biedt een transparante "trace" van precies hoe de agent met je cloudinfrastructuur interageert.

Laten we het stap voor stap doornemen:

1. Tool‑handshakes: Let op de pictogrammen met execute_sql en compute_routes. In de trace geeft de bliksemschicht een toolaanroep aan. De agent heeft niet gegist; hij heeft daadwerkelijk contact gemaakt met de BigQuery MCP‑server om een specifieke SQL‑query op je ordertabel uit te voeren.

2. Sequentiële logica: De trace toont een duidelijke volgorde van acties. Eerst haalt hij de data op via BigQuery (het eerste vinkje). Zodra hij de magazijn- en klantadressen heeft, zie je meerdere compute_routes‑aanroepen. De agent "loopt" intelligent door de vertraagde orders om echte afstandsdata op te halen van de Maps MCP‑server.

3. Definitieve synthese: Onderaan de trace staat het uiteindelijke antwoord.

Kijk naar de data:

• ORD-101: afstand is 380 mijl.
• ORD-103: afstand is 352 mijl.

Omdat we de agent de logica gaven: "Als afstand > 500 mijl, raad Luchtvervoer aan, anders Regional Express Ground," paste de agent deze bedrijfsregel correct toe op beide orders en zette ze om in een mooie Markdown‑tabel.

Conclusie

We hebben zojuist een functionele logistiekagent gebouwd zonder een regel aangepaste API‑code voor BigQuery of Google Maps te schrijven. Door ADK en MCP te gebruiken, hebben we een architectuur gecreëerd die modulair, veilig en developer‑first is.

De toekomst van AI draait niet alleen om pratende chatbots, maar om agents die actie ondernemen. Met deze tools gaan we eindelijk die kant op.

Deze tutorial is een goed startpunt voor je experimenten met de Google ADK en MCP‑servers: 

• Vervang BigQuery door een andere dataset (of zelfs een lokale SQLite MCP‑server) om te zien hoe eenvoudig het is om databronnen te wisselen.
• Vervang Maps door een andere MCP‑server (bijv. GKE voor cluster‑healthchecks) om de plug‑and‑play‑aard te bewijzen.
• Voeg meer bedrijfslogica toe in de prompt (kostenv vergelijking, e‑mailconcept) en test het live in de ADK‑web‑UI.

Wil je meer leren over agentorkestratie, dan raad ik je zeker aan je in te schrijven voor onze Associate AI Engineer for Developers‑carrièreroute.