Next ‘26 Developer Keynote: Building ADK Agents with Skills and Tools

1. Einführung

In diesem Codelab erstellen Sie mit dem Agent Development Kit (ADK) einen komplexen Marathonplaner-Agenten. Sie untersuchen schrittweise die Funktionen des Agenten, von einem gut strukturierten System-Prompt über das dynamische Laden von Skills bis hin zur Zuordnung von MCP-Tools. Abschließend testen Sie den Agenten lokal und stellen ihn in der Agent Runtime (Agent Engine) bereit.

Aufgaben

  • Neues ADK-Agentenprojekt initialisieren
  • Mit einem strukturierten Builder einen robusten System-Prompt erstellen
  • Google Maps MCP-Tools für den Standortkontext in der realen Welt hinzufügen
  • Skills dynamisch in das Toolset des Agenten laden
  • Agentenausführung lokal testen
  • Agenten in der Agent Engine (Cloud Run) bereitstellen

Voraussetzungen

  • Ein Webbrowser wie Chrome
  • Ein Google Cloud-Projekt mit aktivierter Abrechnung
  • Grundlegende Python-Kenntnisse

Dieses Codelab richtet sich an fortgeschrittene Entwickler, die spezialisierte generative KI-Agenten erstellen möchten.

Geschätzte Dauer: 45 Minuten

Die in diesem Codelab erstellten Ressourcen sollten weniger als 2 $kosten.

2. Hinweis

Google Cloud-Projekt erstellen

  1. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
  2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. Informationen zum Prüfen, 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.

  1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
  2. Sobald die Verbindung mit der Cloud Shell hergestellt ist, prüfen Sie Ihre Authentifizierung:
    gcloud auth list
  3. Prüfen Sie, ob Ihr Projekt konfiguriert ist:
    gcloud config get project
  4. Wenn Ihr Projekt nicht wie erwartet festgelegt ist, legen Sie es fest:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Authentifizierung prüfen:

gcloud auth list

Prüfen Sie Ihr Projekt:

gcloud config get project

Legen Sie es bei Bedarf fest:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

APIs aktivieren

Führen Sie diesen Befehl aus, um alle erforderlichen APIs zu aktivieren:

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  mapstools.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com

Google Maps API-Schlüssel erstellen

Wenn Sie die Google Maps MCP-Tools verwenden möchten, müssen Sie einen Maps API-Schlüssel generieren.

  1. Rufen Sie in der Google Cloud Console über die Suchleiste Google Maps Platform > Anmeldedaten auf.
  2. Bestätigen Sie bei Aufforderung Ihr Google Cloud-Projekt.
  3. Klicken Sie auf Anmeldedaten erstellen und wählen Sie API-Schlüssel aus.
  4. Kopieren Sie den generierten API-Schlüssel. Sie benötigen ihn im nächsten Schritt.

3. Umgebung einrichten

Der Code für dieses Codelab wird auf GitHub gehostet. Sie klonen das Repository, das die Verzeichnisstruktur und die erforderlichen Unterkomponenten (z. B. das Verzeichnis skills/) enthält.

  1. Klonen Sie das Repository und rufen Sie den Projektordner auf:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. Richten Sie eine virtuelle Python-Umgebung ein und installieren Sie das ADK:
uv venv
source .venv/bin/activate
uv sync
  1. Legen Sie Ihren Maps API-Schlüssel fest. Die Anwendung liest ihn aus einer Umgebungsvariablen:
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

Umgebungsvariablen konfigurieren

Der Simulator-Agent verwendet eine .env-Datei für die Konfiguration. Kopieren Sie die Beispieldatei und aktualisieren Sie sie mit Ihrer Projekt-ID.

  1. Kopieren Sie die Beispielumgebungsdatei:
cp planner_agent/sample.env planner_agent/.env
  1. Öffnen Sie planner_agent/.env und aktualisieren Sie das Feld GOOGLE_CLOUD_PROJECT mit Ihrer tatsächlichen Google Cloud-Projekt-ID. Aktualisieren Sie das Feld GOOGLE_MAPS_API_KEY mit dem von Ihnen erstellten Google Maps API-Schlüssel.

Die Datei sollte in etwa so aussehen:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true

4. Neuen ADK-Agenten erstellen

Sehen Sie sich die Hauptdatei an, in der der Agent definiert ist: planner_agent/agent.py.

Im Repository build-agents-with-skills wird der Agent mit der Agent-Klasse des ADK initialisiert. Dabei werden das zugrunde liegende Modell und ein Identitätsname angegeben und die in anderen Modulen definierten Anweisungen und Tools abgerufen.

Öffnen Sie planner_agent/agent.py, um den Initialisierungscode zu prüfen:

instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]

# ...

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='planner_agent',
    description=description,
    instruction=instruction,
    tools=tools
)

Die Agent-Klasse abstrahiert den Nachrichtenverlauf, die Toolorchestrierung und die LLM-Kommunikation, sodass Sie sich auf das Verhalten des Agenten konzentrieren können.

Der Agent ist derzeit sehr allgemein. Sie können mit ihm wie mit jedem anderen LLM interagieren.

uv run adk run planner_agent

Mit diesem Befehl wird ein Chat mit dem Agenten gestartet. Er verwendet gemini-3-flash-preview als Modell und kann grundlegende Fragen beantworten.

Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.

Der Agent kennt bereits einige Fakten zu Marathons. Das reicht jedoch nicht aus, um einen ordnungsgemäßen Marathon mit Regeln und Routenplanung zu planen.

5. System-Prompt erstellen

System-Prompts (Anweisungen) bestimmen das Verhalten des Agenten. Anstelle eines einzelnen langen Strings verwendet dieses Projekt einen PromptBuilder (planner_agent/utils.py), um Anweisungen dynamisch zu erstellen.

Öffnen Sie planner_agent/prompts.py, um zu sehen, wie der Prompt in logische Abschnitte unterteilt ist:

from collections import OrderedDict
from .utils import PromptBuilder

ROLE = """\
...
"""

RULES = """\
...
"""

WORKFLOW = """\
...
"""

###

# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        tools=TOOLS_PROMPT_ONLY,
        workflow=WORKFLOW_PROMPT_ONLY,
    )
).build()

# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        skills=SKILLS,
        tools=TOOLS,
        workflow=WORKFLOW,
    )
).build()

In planner_agent/agent.py ist er bereits importiert.

Suchen Sie den Abschnitt mit TODO: Replace Instruction and Description und entfernen Sie die Kommentarzeichen für die Neuzuweisung der Variablen instruction und description.

Dieser Codeabschnitt sollte so aussehen:

instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."

Sie importieren eine Version des Prompts für den Agenten, die keine Tools referenziert. Sie fügen Tools in einem späteren Schritt hinzu.

Sie können diese Version des Agenten testen:

uv run adk run planner_agent

Senden Sie im Chatfenster den folgenden Prompt:

Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Nach einigen Augenblicken sollten Sie eine Antwort ähnlich dieser erhalten:

Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.

As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.

### 1. Intent Alignment
*   **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
*   **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...

Mit einem gut definierten Prompt kommt die Ausgabe dem erwarteten Ergebnis bereits viel näher. Im nächsten Schritt fügen Sie Tools hinzu, um den Agenten auf die nächste Stufe zu heben.

6. Skills und Tools hinzufügen

Suchen Sie in planner_agent/agent.py den Abschnitt mit TODO: Replaces Tools und heben Sie die Auskommentierung der nächsten beiden Zeilen auf, um Skills und Tools zu aktivieren. Ihr Code sollte so aussehen:

instruction=PLANNER_INSTRUCTION
tools=get_tools()

Das ist die einzige Codeänderung, die in diesem Schritt erforderlich ist. Im Rest dieses Abschnitts werden die Konzepte hinter Skills und Tools erläutert.

Skills

Ein Agent-Skill ist eine in sich geschlossene Funktionseinheit, die ein ADK-Agent verwenden kann, um eine bestimmte Aufgabe auszuführen. Ein Agent-Skill kapselt die erforderlichen Anweisungen, Ressourcen und Tools für eine Aufgabe gemäß der Spezifikation des Agent-Skills. Die Struktur eines Skills ermöglicht es, ihn inkrementell zu laden, um die Auswirkungen auf das Kontextfenster des Agenten zu minimieren.

Für den Marathonplaner-Agenten sind drei Skills definiert:

  1. gis-spatial-engineering : Verantwortlich für die Verarbeitung von GeoJSON-Daten zur Erstellung der Marathonstrecke.
  2. mapping : Google Maps-Tools zum Suchen nach Orten und Wetterinformationen verwenden.
  3. race-director : Prüfen, ob die Marathonstrecke den Planungsrichtlinien entspricht.

Skills können Skripts, zusätzliche Assets und Referenzen enthalten.

Die Anwendung lädt alle Skills und stellt sie als Tools in planner_agent/tools.py bereit. Beachten Sie, wie das in der Funktion get_tools() erfolgt:

def get_tools() -> list:
    """Build the planner's tool list with lazy-loaded skills."""
    from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor

    skills_dir = pathlib.Path(__file__).parent / "skills"

    skills = []
    if skills_dir.exists():
        skills = [
            load_skill_from_dir(d)
            for d in sorted(skills_dir.iterdir())
            if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
        ]

    additional_tools = _load_additional_tools(skills_dir)

    skill_toolset = SkillToolset(
        skills=skills,
        code_executor=UnsafeLocalCodeExecutor(),
        additional_tools=additional_tools,
    )

    tools = [
        skill_toolset,
        PreloadMemoryTool(),
    ]

    tools.extend(get_maps_tools())

    return tools

Der interessanteste Teil ist die Methode load_skill_from_dir aus dem ADK. Es gibt eine weitere Möglichkeit, Skills im ADK zu erstellen, nämlich inline. Sie wird in diesem Codelab nicht verwendet, sieht aber ungefähr so aus:

from google.adk.skills import models

greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "A friendly greeting skill that can say hello to a specific person."
        ),
    ),
    instructions=(
        "Step 1: Read the 'references/hello_world.txt' file to understand how"
        " to greet the user. Step 2: Return a greeting based on the reference."
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "Hello! So glad to have you here!",
            "example.md": "This is an example reference.",
        },
    ),
)

Zuordnungstools hinzufügen

Der Marathonplaner benötigt einen räumlichen Kontext, um Routen zu generieren. Sie stellen diesen bereit, indem Sie den Google Maps MCP-Server (Model Context Protocol) einbinden.

Beachten Sie in planner_agent/tools.py, wie der MCP-Server mit dem Tool ApiRegistry registriert wird:

from google.adk.integrations.api_registry import ApiRegistry

class MapsApiRegistry(ApiRegistry):
    """ApiRegistry subclass that strips ADC headers to force API key auth."""

    def get_toolset(self, *args, **kwargs):  # noqa: ANN002, ANN003
        toolset = super().get_toolset(*args, **kwargs)
        conn = getattr(toolset, "_connection_params", None)
        headers = getattr(conn, "headers", None) if conn else None
        if headers:
            headers.pop("Authorization", None)  # type: ignore[union-attr]
            headers.pop("x-goog-user-project", None)  # type: ignore[union-attr]
        return toolset

def get_maps_tools() -> list:
    """Return Maps MCP toolset if configured."""
    project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
    maps_key = _resolve_maps_key()

    if not project_id or not maps_key:
        return []

    # Map the MCP server location on Google Cloud
    mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
    
    # Initialize the custom API registry that supports header injection
    api_registry = MapsApiRegistry(
        api_registry_project_id=project_id,
        header_provider=header_provider,
    )
    return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]

Durch Hinzufügen des MCP-Toolsets kann der Agent automatisch Google Maps nach Routen, Höhenangaben und Standortdetails abfragen.

7. Agenten lokal ausführen

Nachdem der Agent, der Prompt und die Tools miteinander verbunden sind, führen Sie den Agenten lokal aus. Dieses Mal verwenden Sie adk web, damit Sie die Ereignisse zum Laden von Skills und zum Aufrufen von Tools sehen können.

uv run adk web

Die Ausgabe sollte in etwa so aussehen:

INFO:     Started server process [99665]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| 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)
  1. Öffnen Sie Ihren Browser und rufen Sie die im Terminal angezeigte URL auf (in der Regel http://localhost:8000).
  2. Wählen Sie oben links im Drop-down-Menü planner_agent aus.
  3. Senden Sie im Chatfenster den folgenden Prompt:
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Sie sollten sehen, dass Skills geladen und Tools aufgerufen werden. Nach einigen Augenblicken generiert der Agent einen Marathonplan.

Die Benutzeroberfläche sollte in etwa so aussehen:

ADK Web-UI

8. Agent bereitstellen

Wenn Sie mit der lokalen Leistung des Agenten zufrieden sind, können Sie ihn in der Agent Engine bereitstellen, die den Agenten sicher in Cloud Run hostet.

Verwenden Sie den ADK-CLI-Bereitstellungsbefehl, um den Agenten bereitzustellen:

uv run adk deploy agent_engine \
  --env_file planner_agent/.env \
  planner_agent

Wenn die Bereitstellung abgeschlossen ist, gibt die CLI einen sicher gehosteten Endpunkt für Ihren Agenten aus. Sie können diesen Endpunkt jetzt in Front-End-Anwendungen, Chatbots oder andere Back-End-Systeme einbinden. Sie können den Agenten auch mit dem Agent Runtime Playground testen.

Die Ausgabe sieht so aus:

Files and dependencies resolved
Deploying to agent engine...
✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>

Mit dem bereitgestellten Python-Skript können Sie mit dem Agenten kommunizieren.

  1. Kopieren Sie die Beispielumgebungsdatei:
cp sample.env .env
  1. Öffnen Sie .env und aktualisieren Sie das Feld GOOGLE_CLOUD_PROJECT mit Ihrer tatsächlichen Google Cloud-Projekt-ID.

Die Datei sollte in etwa so aussehen:

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
  1. Sie können Agenten in Ihrem Projekt auflisten.
python main.py list

Die Ausgabe sollte in etwa so aussehen:

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

Sobald Sie die ID des bereitgestellten Agenten haben, können Sie einen Prompt senden:

export AGENT_ID=<AGENT_ID>

python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"

Die Ausgabe sollte in etwa so aussehen:

Streaming response from agent <AGENT_ID>:

{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...

9. Bereinigen

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

Löschen Sie den Cloud Run-Dienst, der durch die Bereitstellung erstellt wurde:

python main.py delete --agent-id ${AGENT_ID}

Wenn Sie den Maps API-Schlüssel in Secret Manager gespeichert haben, löschen Sie das Secret:

gcloud secrets delete maps-api-key --project=$PROJECT_ID

Wenn Sie für dieses Codelab ein neues Google Cloud-Projekt erstellt haben, können Sie das gesamte Projekt löschen, um alle zugehörigen Ressourcen und APIs zu entfernen:

gcloud projects delete $PROJECT_ID

10. Glückwunsch

Glückwunsch! Sie haben mit dem ADK einen komplexen Marathonplaner-Agenten erstellt.

Lerninhalte

  • Agent Development Kit (ADK)-Projekt initialisieren
  • PromptBuilder für modulare System-Prompts verwenden
  • Zuordnungsfunktionen mit MCP-Tools und ApiRegistry einbinden
  • Skills mit SkillToolset bedingt laden
  • Lokal testen und in der Agent Engine bereitstellen

Referenzdokumente