ADK-Agent in Cloud Run erstellen und bereitstellen

1. Einführung

In diesem Lab geht es um die Implementierung und Bereitstellung eines Client-Agent-Dienstes. Sie verwenden das Agent Development Kit (ADK), um einen KI-Agenten zu erstellen, der Tools verwendet.

In diesem Lab erstellen wir einen Zoo-Agenten, der Wikipedia verwendet, um Fragen zu Tieren zu beantworten.

Von links nach rechts stehen ein Löwe, zwei Pinguine, eine Person mit Safarihut, ein Elefant und ein Bär mit dem Rücken zum Betrachter und blicken auf eine große rot-weiße Rakete, die in einen blauen Himmel mit weißen Wolken startet. Im Hintergrund sind zwei weitere kleinere Raketen zu sehen, die starten. Die Szene spielt in einem Zoogehege mit einem Holzzaun und Felsklippen.

Schließlich stellen wir den Reiseführer-Agenten in Google Cloud Run bereit, anstatt ihn nur lokal auszuführen.

Vorbereitung

  • Google Cloud-Projekt mit aktivierter Abrechnungsfunktion.

Lerninhalte

  • So strukturieren Sie ein Python-Projekt für die ADK-Bereitstellung.
  • Implementieren eines Agents mit Tools mit google-adk
  • So stellen Sie eine Python-Anwendung als serverlosen Container in Cloud Run bereit.
  • So konfigurieren Sie die sichere Dienst-zu-Dienst-Authentifizierung mit IAM-Rollen.
  • So löschen Sie Cloud-Ressourcen, um zukünftige Kosten zu vermeiden.

Voraussetzungen

  • Ein Google Cloud-Konto und ein Google Cloud-Projekt
  • Ein Webbrowser wie Chrome

2. Warum in Cloud Run bereitstellen?

Cloud Run ist eine gute Wahl für das Hosting von ADK-Agents, da es sich um eine serverlose Plattform handelt. Sie können sich also auf Ihren Code konzentrieren und müssen sich nicht um die Verwaltung der zugrunde liegenden Infrastruktur kümmern. Wir übernehmen die operative Arbeit für Sie.

Stellen Sie sich das wie einen Pop-up-Store vor: Er öffnet nur, wenn Kundinnen und Kunden (Anfragen) kommen, und nutzt dann Ressourcen. Wenn keine Kundinnen und Kunden da sind, schließt er komplett und Sie zahlen nicht für ein leeres Geschäft.

Wichtigste Funktionen

Container überall ausführen:

  • Sie stellen einen Container (Docker-Image) mit Ihrer Anwendung darin bereit.
  • Cloud Run führt sie in der Infrastruktur von Google aus.
  • Es sind kein Patching des Betriebssystems und keine VM-Einrichtung nötig und es gibt keine Skalierungsprobleme.

Autoscaling:

  • Wenn niemand Ihre App verwendet, werden 0 Instanzen ausgeführt. Die Anzahl der Instanzen wird auf 0 skaliert, was kostengünstig ist.
  • Wenn 1.000 Anfragen eingehen, werden so viele Kopien wie nötig erstellt.

Standardmäßig zustandslos:

  • Jede Anfrage kann an eine andere Instanz gesendet werden.
  • Wenn Sie den Zustand speichern müssen, verwenden Sie einen externen Dienst wie Cloud SQL, Firestore oder Memorystore.

Unterstützung beliebiger Sprachen oder Frameworks:

  • Solange die Anwendung in einem Linux-Container ausgeführt wird, ist es Cloud Run egal, ob sie in Python, Go, Node.js, Java oder .NET geschrieben ist.

Nur für die tatsächliche Nutzung zahlen:

3. Projekt einrichten

Google-Konto

Wenn Sie noch kein privates Google-Konto haben, müssen Sie ein Google-Konto erstellen.

Verwenden Sie stattdessen ein privates Konto.

In der Google Cloud Console anmelden

Melden Sie sich mit einem privaten Google-Konto in der Google Cloud Console an.

Abrechnung aktivieren

Privates Rechnungskonto einrichten

Wenn Sie die Abrechnung mit Google Cloud-Guthaben eingerichtet haben, können Sie diesen Schritt überspringen.

Klicken Sie hier, um die Abrechnung in der Cloud Console zu aktivieren und ein privates Rechnungskonto einzurichten.

Hinweise:

  • Die Kosten für Cloud-Ressourcen für dieses Lab sollten weniger als 1 $betragen.
  • Sie können die Schritte am Ende dieses Labs ausführen, um Ressourcen zu löschen und so weitere Kosten zu vermeiden.
  • Neuen Nutzern steht die kostenlose Testversion mit einem Guthaben von 300$ zur Verfügung.

Projekt erstellen (optional)

Wenn Sie kein aktuelles Projekt haben, das Sie für dieses Lab verwenden möchten, erstellen Sie hier ein neues Projekt.

4. Cloud Shell-Editor öffnen

  1. Klicken Sie auf diesen Link, um direkt zum Cloud Shell-Editor zu gelangen.
  2. Wenn Sie heute an irgendeinem Punkt zur Autorisierung aufgefordert werden, klicken Sie auf Autorisieren, um fortzufahren.Klicken Sie, um Cloud Shell zu autorisieren.
  3. Wenn das Terminal nicht unten auf dem Bildschirm angezeigt wird, öffnen Sie es:
    • Klicken Sie auf Ansehen.
    • Klicken Sie auf TerminalNeues Terminal im Cloud Shell-Editor öffnen.

5. APIs aktivieren

Wenn Sie Cloud Run, Artifact Registry, Cloud Build, Vertex AI und Compute Engine verwenden möchten, müssen Sie die entsprechenden APIs in Ihrem Google Cloud-Projekt aktivieren.

  • Aktivieren Sie die APIs im Terminal:
    gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com
    Nach Abschluss der Ausführung sollte eine Ausgabe wie die folgende angezeigt werden:
    Operation "operations/acat.p2-[GUID]" finished successfully.

Einführung in die APIs

  • Mit der Cloud Run Admin API (run.googleapis.com) können Sie Frontend- und Backend-Dienste, Batchjobs oder Websites in einer vollständig verwalteten Umgebung ausführen. Die Infrastruktur für die Bereitstellung und Skalierung Ihrer Containeranwendungen wird von GKE übernommen.
  • Die Artifact Registry API (artifactregistry.googleapis.com) bietet ein sicheres, privates Repository zum Speichern Ihrer Container-Images. Es ist die Weiterentwicklung von Container Registry und lässt sich nahtlos in Cloud Run und Cloud Build einbinden.
  • Die Cloud Build API (cloudbuild.googleapis.com) ist eine serverlose CI/CD-Plattform, die Ihre Builds in der Google Cloud-Infrastruktur ausführt. Damit wird Ihr Container-Image in der Cloud aus Ihrem Dockerfile erstellt.
  • Mit der Vertex AI API (aiplatform.googleapis.com) kann Ihre bereitgestellte Anwendung mit Gemini-Modellen kommunizieren, um KI-Kernaufgaben auszuführen. Sie bietet die einheitliche API für alle KI-Dienste von Google Cloud.
  • Die Compute Engine API (compute.googleapis.com) bietet sichere und anpassbare virtuelle Maschinen, die in der Infrastruktur von Google ausgeführt werden. Cloud Run wird zwar verwaltet, die Compute Engine API ist jedoch häufig als grundlegende Abhängigkeit für verschiedene Netzwerk- und Rechenressourcen erforderlich.

6. Bereiten Sie Ihre Entwicklungsumgebung vor

Verzeichnis erstellen

  1. Erstellen Sie im Terminal das Projektverzeichnis und die erforderlichen Unterverzeichnisse:
    cd && mkdir zoo_guide_agent && cd zoo_guide_agent
  2. Führen Sie im Terminal den folgenden Befehl aus, um das Verzeichnis zoo_guide_agent im Cloud Shell-Editor-Explorer zu öffnen:
    cloudshell open-workspace ~/zoo_guide_agent
  3. Der Explorer-Bereich auf der linken Seite wird aktualisiert. Das von Ihnen erstellte Verzeichnis sollte jetzt angezeigt werden.
    Screenshot des neuen Verzeichnisses in der Explorer-Seitenleiste

Projekt festlegen

  1. Legen Sie im Terminal Ihr Projekt mit diesem Befehl fest:
    gcloud config set project [PROJECT_ID]
    Beispiel: gcloud config set project lab-project-id-example Projekt-ID im Cloud Shell Editor-Terminal festlegen
  2. Es sollte folgende Meldung angezeigt werden:
    Updated property [core/project].

Installationsanforderungen

  1. Führen Sie den folgenden Befehl im Terminal aus, um die Datei requirements.txt zu erstellen.
    cloudshell edit requirements.txt
  2. Fügen Sie der neu erstellten Datei requirements.txt Folgendes hinzu:
    google-adk==1.14.0
langchain-community==0.3.27
wikipedia==1.4.0
  3. Erstellen und aktivieren Sie im Terminal eine virtuelle Umgebung mit uv. So wird sichergestellt, dass die Projektabhängigkeiten nicht mit dem System-Python in Konflikt stehen.
    uv venv
source .venv/bin/activate
  4. Installieren Sie die erforderlichen Pakete in Ihrer virtuellen Umgebung im Terminal.
    uv pip install -r requirements.txt

Umgebungsvariablen einrichten

  • Verwenden Sie den folgenden Befehl im Terminal, um die Datei .env zu erstellen.
    # 1. Set the variables in your terminal first
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
SA_NAME=lab2-cr-service

# 2. Create the .env file using those variables
cat <<EOF > .env
PROJECT_ID=$PROJECT_ID
PROJECT_NUMBER=$PROJECT_NUMBER
SA_NAME=$SA_NAME
SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
MODEL="gemini-2.5-flash"
EOF

7. Agent-Workflow erstellen

__init__.py-Datei erstellen

  1. Erstellen Sie die Datei init.py, indem Sie Folgendes im Terminal ausführen:
    cloudshell edit __init__.py
    Diese Datei teilt Python mit, dass das Verzeichnis „zoo_guide_agent“ ein Paket ist.
  2. Fügen Sie der neuen __init__.py-Datei den folgenden Code hinzu:
    from . import agent

Erstellen der agent.py-Datei

  1. Erstellen Sie die Hauptdatei agent.py, indem Sie den folgenden Befehl in das Terminal einfügen.
    cloudshell edit agent.py
  2. Importe und Ersteinrichtung: Fügen Sie der derzeit leeren Datei agent.py den folgenden Code hinzu:
    import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")
    In diesem ersten Block der Datei agent.py werden alle erforderlichen Bibliotheken aus dem ADK und Google Cloud eingebunden. Außerdem wird die Protokollierung eingerichtet und die Umgebungsvariablen aus der Datei .env geladen, was für den Zugriff auf Ihr Modell und Ihre Server-URL entscheidend ist.
  3. Tools definieren: Ein Agent ist nur so gut wie die Tools, die er verwenden kann. Fügen Sie am Ende von agent.py den folgenden Code ein, um die Tools zu definieren:
    # Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)
    Die Tools im Detail
    • add_prompt_to_state 📝: Dieses Tool merkt sich, was ein Zoobesucher fragt. Wenn eine Besucherin oder ein Besucher fragt: „Wo sind die Löwen?“, speichert dieses Tool die Frage im Gedächtnis des KI-Agenten, sodass die anderen KI-Agenten im Workflow wissen, wonach sie suchen müssen.
      Funktionsweise:Es handelt sich um eine Python-Funktion, die den Prompt des Besuchers in das freigegebene tool_context.state-Wörterbuch schreibt. Dieser Toolkontext stellt das Kurzzeitgedächtnis des KI-Agenten für eine einzelne Unterhaltung dar. Daten, die von einem KI-Agenten im Zustand gespeichert wurden, können vom nächsten KI-Agenten im Workflow gelesen werden.
    • LangchainTool 🌍: Damit erhält der Reiseführer-Agent allgemeines Wissen über die Welt. Wenn eine Besucherin oder ein Besucher eine Frage stellt, die nicht in der Datenbank des Zoos enthalten ist, wie z. B.: „Was fressen Löwen in freier Wildbahn?“, kann der KI-Agent mit diesem Tool die Antwort bei Wikipedia nachschlagen.
      Funktionsweise:Er fungiert als Adapter, sodass unser Agent das vorgefertigte Tool „WikipediaQueryRun“ aus der LangChain-Bibliothek verwenden kann.
      Der freundlich aussehende Roboter hält ein Notizbuch mit Tierzeichnungen und einer Gedankenblase mit einem Löwen und spricht mit einem Mann und einem kleinen Jungen mit einem Rucksack. Im Hintergrund sind Giraffen und andere Zoo-Elemente zu sehen. Palmen rahmen den Eingang ein.
  4. Spezialisten-Agents definieren: Fügen Sie den folgenden Code unten in agent.py ein, um die Agents comprehensive_researcher und response_formatter zu definieren:
    # 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)
    • Der comprehensive_researcher-Agent ist das „Gehirn“ unserer Operation. Er nimmt den Prompt des Nutzers aus dem freigegebenen State, prüft, ob es sich um das Wikipedia-Tool handelt, und entscheidet, welche Tools verwendet werden sollen, um die Antwort zu finden.
    • Die Rolle des response_formatter-Agenten ist die Präsentation. Er nimmt die vom Researcher-Agenten gesammelten Rohdaten (über den Status übergeben) und nutzt die Sprachkenntnisse des LLM, um sie in eine freundliche, konversationelle Antwort umzuwandeln.
      Der Roboter mit leuchtend blauen Augen sitzt vor einem großen gekrümmten Monitor, auf dem links MCP ZOO SERVER und rechts eine ZOO-Wikipedia-Seite angezeigt werden. Tiersymbole sind auf der Serveroberfläche sichtbar. Der Schreibtisch hat mehrere leuchtend blaue Touchpads. Im Hintergrund ist eine Skyline durch große Fenster zu sehen.
  5. Workflow-Agent definieren: Fügen Sie diesen Codeblock unten in agent.py ein, um den sequenziellen Agenten tour_guide_workflow zu definieren:
    tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)
    Der Workflow-Agent fungiert als „Backoffice“-Manager für die Zoo-Tour. Sie nimmt die Rechercheanfrage entgegen und sorgt dafür, dass die beiden oben definierten Agents ihre Aufgaben in der richtigen Reihenfolge ausführen: zuerst Recherche, dann Formatierung. So entsteht ein vorhersehbarer und zuverlässiger Prozess für die Beantwortung der Frage eines Besuchers.
    Wie:Es handelt sich um einen SequentialAgent, eine spezielle Art von Agent, der nicht selbstständig denkt. Seine einzige Aufgabe besteht darin, eine Liste von sub_agents (dem Researcher und dem Formatter) in einer festen Reihenfolge auszuführen und den gemeinsamen Speicher automatisch von einem zum nächsten zu übergeben.
  6. Hauptworkflow zusammenstellen: Fügen Sie diesen letzten Codeblock unten in agent.py ein, um root_agent zu definieren:
    root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)
    Das ADK-Framework verwendet root_agent als Ausgangspunkt für alle neuen Unterhaltungen. Die Hauptaufgabe besteht darin, den gesamten Prozess zu orchestrieren. Er fungiert als anfänglicher Controller und verwaltet die erste Runde der Unterhaltung.
    Es werden drei Roboter dargestellt: Ein Greeter-Bot links schreibt auf ein Notizbuch mit einer Denkblase eines Löwen, ein Researcher-Bot in der Mitte sitzt an einem Schreibtisch mit einem Computer, auf dem Daten angezeigt werden, und ein Fragepfeil zeigt darauf. Ein Presenter-Bot rechts lächelt und hält ein Diagramm mit der Aufschrift „Analysierte Daten“ in der Hand. Ein Pfeil zeigt vom Researcher-Bot darauf. Im Hintergrund sind Giraffen und Elefanten zu sehen und Palmen umrahmen die Szene.

Die vollständige agent.py-Datei

Ihre agent.py-Datei ist jetzt fertig. So können Sie sehen, wie jede Komponente – Tools, Worker-KI-Agenten und Manager-KI-Agenten – eine bestimmte Rolle bei der Erstellung des endgültigen, intelligenten Systems spielt.

Die vollständige Datei sollte so aussehen:

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
        you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

Als Nächstes erfolgt die Bereitstellung.

8. Anwendung auf die Bereitstellung vorbereiten

Endgültige Struktur prüfen

Prüfen Sie vor der Bereitstellung, ob Ihr Projektverzeichnis die richtigen Dateien enthält.

  • Ihr zoo_guide_agent-Ordner sollte so aussehen:
    zoo_guide_agent/
├── .env
├── __init__.py
├── agent.py
└── requirements.txt

IAM-Berechtigungen einrichten

Nachdem Sie Ihren lokalen Code vorbereitet haben, müssen Sie als Nächstes die Identität einrichten, die Ihr Agent in der Cloud verwenden soll.

  1. Laden Sie die Variablen im Terminal in Ihre Shell-Sitzung.
    source .env
  2. Erstellen Sie ein dediziertes Dienstkonto für Ihren Cloud Run-Dienst, damit es über eine eigene spezifische Berechtigung verfügt. Fügen Sie Folgendes in das Terminal ein:
    gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for lab 2 "
    Wenn Sie eine spezielle Identität für diese Anwendung erstellen, hat der Agent nur die Berechtigungen, die er benötigt, anstatt ein Standardkonto mit zu umfassendem Zugriff zu verwenden.
  3. Weisen Sie dem Dienstkonto die Rolle „Vertex AI-Nutzer“ zu, damit es die Modelle von Google aufrufen darf.
    # Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

9. KI-Agenten mit der ADK-CLI bereitstellen

Ihr lokaler Code ist fertig und Ihr Google Cloud-Projekt ist vorbereitet. Jetzt können Sie den KI-Agenten bereitstellen. Sie verwenden den Befehl adk deploy cloud_run, ein praktisches Tool, das den gesamten Bereitstellungsworkflow automatisiert. Mit diesem einzelnen Befehl wird Ihr Code verpackt, ein Container-Image erstellt, per Push in Artifact Registry übertragen und der Dienst in Cloud Run gestartet, sodass er im Web zugänglich ist.

  1. Führen Sie im Terminal den folgenden Befehl aus, um den Agent bereitzustellen.
    # Run the deployment command
uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT
    Mit dem Befehl uvx können Sie Befehlszeilentools ausführen, die als Python-Pakete veröffentlicht wurden, ohne dass diese Tools global installiert sein müssen.
  2. Wenn Sie die folgende Meldung sehen:
    Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?
    Geben Sie in diesem Fall Y ein und drücken Sie die Eingabetaste.
  3. Wenn Sie die folgende Meldung sehen:
    Allow unauthenticated invocations to [your-service-name] (y/N)?.
    Geben Sie y ein und drücken Sie die Eingabetaste. So sind für dieses Lab nicht authentifizierte Aufrufe möglich, was das Testen erleichtert. Bei erfolgreicher Ausführung wird mit dem Befehl die URL des bereitgestellten Cloud Run-Dienstes zurückgegeben. (Das sieht etwa so aus: https://zoo-tour-guide-123456789.europe-west1.run.app)
  4. Kopieren Sie die URL des bereitgestellten Cloud Run-Dienstes für die nächste Aufgabe.

10. Bereitgestellten KI-Agenten testen

Nachdem Ihr Agent jetzt in Cloud Run aktiv ist, führen Sie einen Test durch, um zu bestätigen, dass die Bereitstellung erfolgreich war und der Agent wie erwartet funktioniert. Sie verwenden die öffentliche Dienst-URL (z. B. https://zoo-tour-guide-123456789.europe-west1.run.app/), um auf die Weboberfläche des ADK zuzugreifen und mit dem Agenten zu interagieren.

  1. Öffnen Sie die öffentliche Cloud Run-Dienst-URL in Ihrem Webbrowser. Da Sie --with_ui flag verwendet haben, sollten Sie die ADK-Entwickler-UI sehen.
  2. Aktiviere rechts oben die Option Token Streaming.
     Sie können jetzt mit dem Zoo-Agent interagieren.
  3. Geben Sie hello ein und drücken Sie die Eingabetaste, um eine neue Unterhaltung zu beginnen.
  4. Sehen Sie sich das Ergebnis an. Der KI-Agent sollte schnell mit einer Begrüßung antworten, die in etwa so aussieht:
    "Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
  5. Stellen Sie dem Agenten Fragen wie:
    Where can I find the polar bears in the zoo and what is their diet?
    Screenshot des ADK-Agents, der eine Reihe von Aktionen ausführt: „add_prompt_to_state“, „transfer_to_agent“, „wikipedia“ und „get_animals_by_species“. In der ersten Antwort heißt es: „Ich kann dir nicht sagen, wo sich die Eisbären in diesem Zoo befinden, aber ich kann dir etwas über ihre Ernährung erzählen.“ In der zweiten Antwort heißt es: „Die Eisbären befinden sich in der Arktisausstellung am Polarweg. Ich kann mit den verfügbaren Tools keine Informationen zu ihrer Ernährung abrufen.&#39; In der dritten, umfassendsten Antwort heißt es: „Gerne erzähle ich dir etwas über unsere Eisbären! Sie finden unsere Eisbären in der Arktis-Ausstellung auf dem Polarweg. Wir haben hier drei Eisbären: Snowflake, die 7 Jahre alt ist. Blizzard, der 5 Jahre alt ist. Iceberg, der 9 Jahre alt ist. Eisbären sind hauptsächlich Fleischfresser. Sie sind auf Robben spezialisiert, insbesondere auf Ringelrobben. Sie fressen auch Walrosse, Belugawale und einige Landtiere.“

Durch einen KI-Agenten gestützter Ablauf

Ihr System funktioniert wie ein intelligentes Multi-Agent-Team. Der Prozess wird durch eine klare Abfolge gesteuert, um einen reibungslosen und effizienten Ablauf von der Frage einer Nutzerin oder eines Nutzers bis zur detaillierten Antwort zu gewährleisten.

1. Der Zoo-Greeter (Der Welcome Desk)

Der gesamte Prozess beginnt mit dem Begrüßungs-KI-Agenten.

  • Aufgabe: Die Unterhaltung beginnen. Die Anweisung lautet, die Nutzerin bzw. den Nutzer zu begrüßen und zu fragen, über welches Tier die Person mehr erfahren möchte.
  • Tool: Wenn die Nutzerin bzw. der Nutzer antwortet, verwendet der Begrüßungs-KI-Agent das Tool „add_prompt_to_state“, um die genauen Worte der Person zu erfassen (z. B. „Erzähl mir etwas über Löwen“), und speichert sie im Arbeitsspeicher des Systems.
  • Übergabe: Nachdem der Prompt gespeichert wurde, übergibt er die Steuerung sofort an seinen Unter-KI-Agenten, den tour_guide_workflow.

2. Der umfassende Researcher (der Super-Researcher)

Dies ist der erste Schritt im Hauptworkflow und das „Gehirn“ des Dienstes. Statt eines großen Teams haben Sie jetzt einen einzigen, hochqualifizierten KI-Agenten, der auf alle verfügbaren Informationen zugreifen kann.

  • Aufgabe: Die Frage der Nutzerin bzw. des Nutzers analysieren und einen intelligenten Plan erstellen. Dabei wird die Funktion des Sprachmodells zur Verwendung von Tools genutzt, um zu entscheiden, ob Folgendes erforderlich ist:
    • Allgemeinwissen aus dem Web (über die Wikipedia API)
    • Beides im Fall komplexer Fragen

3. Der Antwortformatierer (Der Moderator)

Sobald der gründliche Rechercheur alle Fakten zusammengetragen hat, ist dies der letzte KI-Agent, der ausgeführt wird.

  • Aufgabe: Als freundliche Stimme der Zooführung fungieren. Dieser KI-Agent nimmt die Rohdaten (die aus einer oder aus beiden Quellen stammen können) und bereitet sie auf.
  • Aktion: Die Informationen werden in einer einzigen, zusammenhängenden und ansprechenden Antwort zusammengefasst. Gemäß den Anweisungen werden zuerst die spezifischen Zoo-Informationen und dann die interessanten allgemeinen Fakten präsentiert.
  • Endergebnis: Der von diesem KI-Agenten generierte Text ist die vollständige, detaillierte Antwort, die im Chatfenster zu sehen ist.

Weitere Informationen zum Erstellen von KI-Agenten finden Sie in den folgenden Ressourcen:

  1. ADK-Dokumentation
  2. Benutzerdefinierte Tools für ADK-Agents erstellen

11. Umgebung bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, können Sie entweder das Projekt löschen, das die Ressourcen enthält, oder das Projekt beibehalten und die einzelnen Ressourcen löschen.

Cloud Run-Dienste und -Images löschen

Wenn Sie das Google Cloud-Projekt beibehalten, aber die in diesem Lab erstellten Ressourcen entfernen möchten, müssen Sie sowohl den laufenden Dienst als auch das in der Registry gespeicherte Container-Image löschen.

  • Führen Sie im Terminal die folgenden Befehle aus:
    gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet

Projekt löschen (optional)

Wenn Sie ein neues Projekt speziell für dieses Lab erstellt haben und es nicht noch einmal verwenden möchten, löschen Sie es am besten. So werden alle Ressourcen (einschließlich des Dienstkontos und aller verborgenen Build-Artefakte) vollständig entfernt.

  • Führen Sie im Terminal den folgenden Befehl aus und ersetzen Sie [YOUR_PROJECT_ID] durch Ihre tatsächliche Projekt-ID:
    gcloud projects delete $PROJECT_ID

12. Glückwunsch

Sie haben eine Multi-Agenten-KI-Anwendung erfolgreich in Google Cloud erstellt und bereitgestellt.

Zusammenfassung

In diesem Lab haben Sie aus einem leeren Verzeichnis einen aktiven, öffentlich zugänglichen KI-Dienst erstellt. So sieht das Ergebnis aus:

  • Sie haben ein spezialisiertes Team erstellt: Anstelle einer generischen KI haben Sie einen „Researcher“ (Recherchierer) zum Auffinden von Fakten und einen „Formatter“ (Formatierer) zum Überarbeiten der Antwort erstellt.
  • Sie haben ihnen Tools zur Verfügung gestellt: Sie haben Ihre Agents über die Wikipedia API mit der Außenwelt verbunden.
  • Sie haben es geschafft: Sie haben Ihren lokalen Python-Code als serverlosen Container in Cloud Run bereitgestellt und mit einem dedizierten Dienstkonto gesichert.

Behandelte Themen

  • Wie Sie ein Python-Projekt für die Bereitstellung mit dem ADK strukturieren.
  • Multi-Agent-Workflow mit [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/) implementieren
  • Externe Tools wie die Wikipedia API einbinden
  • So stellen Sie einen Agent mit dem Befehl adk deploy in Cloud Run bereit.

13. Umfrage

Ausgabe:

Wie werden Sie diese Anleitung verwenden?

Nur lesen Lesen und Übungen durchführen