1. Einführung
Übersicht
In diesem Lab wird gezeigt, wie Sie einen ereignisgesteuerten Aufruf eines ADK-Agents, der in Cloud Run bereitgestellt wird, mithilfe von Eventarc- und Pub/Sub-Diensten sicher implementieren. In den meisten Fällen wird ein Agent direkt von einem Nutzer oder einem anderen Agent aufgerufen. Wenn ein Agent jedoch in vorhandene ereignisbasierte Workflows integriert wird, erfordert ein direkter Aufruf Änderungen an der vorhandenen Software. Wenn Sie einen Agent-Aufruf basierend auf einem Ereignis auslösen, können Sie einen Agent in bestehende Workflows einbinden, ohne dass Änderungen an den Workflows erforderlich sind.
Aufgaben
In diesem Lab erstellen Sie eine ZooKeeper-Anwendung mit einem KI-Agenten, die einige Tools verwendet, um Informationen zu Tieren im imaginären Zoo bereitzustellen.
Sie stellen die ZooKeeper-Anwendung als Dienst in Cloud Run bereit. Cloud Run ist eine vollständig verwaltete, serverlose Computing-Plattform, auf der zustandslose Container in der Infrastruktur von Google ausgeführt werden. Anschließend richten Sie einen Eventarc-Trigger ein, der den Dienstendpunkt aufruft, um Nachrichten, die in einem Pub/Sub-Thema veröffentlicht werden, asynchron zu verarbeiten. Sie sorgen dafür, dass die Bereitstellung Best Practices entspricht, einschließlich der Verwendung von zugewiesenen IAM-Dienstkonten, der Gewährung des Zugriffs mit den geringsten Berechtigungen und der Minimierung einer potenziellen Angriffsfläche, indem Sie den Endpunkt der ZooKeeper-Anwendung nur für Eventarc verfügbar machen. Dazu verwenden Sie die Cloud Shell und die Cloud Console. Sie verwenden ADK- und Cloud SDK-Bibliotheken für Python. Sie verwenden die gcloud CLI, um das Verhalten zu prüfen.
Lerninhalte
- Stellen Sie Ihren ADK-Agent in Google Cloud Run bereit.
- Eventarc-Trigger in ADK-Agent einbinden, der in Google Cloud Run ausgeführt wird
- Sichern Sie Ihre Bereitstellung und Integration mit Eventarc mithilfe des Prinzips der geringsten Berechtigung mit Google Cloud IAM.
- Nachrichten in Pub/Sub veröffentlichen und daraus abrufen
- Minimieren Sie die öffentliche Verfügbarkeit Ihrer in Google Cloud Run bereitgestellten Anwendung.
Voraussetzungen
- Chrome-Webbrowser †
- Ein privates Google-Konto‡
- Ein Google Cloud-Projekt, das mit einem aktiven Rechnungskonto verknüpft ist
Ihr Konto muss IAM-Zugriff auf das Projekt haben, damit Sie Ressourcen bereitstellen und den IAM-Zugriff auf diese Ressourcen konfigurieren können.
† Die Nutzerfreundlichkeit bei der Verwendung anderer Browser kann von der im Lab beschriebenen abweichen.
‡ Bei der Verwendung eines Unternehmens- oder Schulkontos können einige der im Lab beschriebenen Vorgänge eingeschränkt sein.
2. Umgebung einrichten
Damit Sie eine voll funktionsfähige Entwicklungsumgebung für das Lab haben, verwenden Sie Google Cloud Shell, in der alle erforderlichen Tools vorinstalliert sind. Folgen Sie der Anleitung, um die Umgebung einzurichten.
Wenn Sie noch kein Google-Konto haben, können Sie hier eines erstellen.
Anleitung zur Einrichtung
- Melden Sie sich mit Ihrem Google-Konto in der Google Cloud Console an.
- 👉 Öffnen Sie die Projektauswahl in der oberen Navigationsleiste (möglicherweise wird „Projekt auswählen“ oder ein vorhandener Projektname angezeigt) oder klicken Sie auf die Tastenkombination
Ctrl+Ound wählen Sie ein vorhandenes Projekt aus oder erstellen Sie ein neues Projekt.Das Erstellen eines neuen Projekts dauert einige Sekunden. Warten Sie, bis es bereit ist, und wählen Sie es dann über die Projektauswahl aus.
- 👉 Klicken Sie oben in der Google Cloud Console auf das Symbol Cloud Shell. (mit dem roten Rechteck markiert):
Klicken Sie bei Aufforderung im Pop-up-Dialogfeld auf **Autorisieren**, um Cloud Shell die Verwendung der Anmeldedaten Ihres Kontos zu erlauben.
- 👉💻 Achten Sie darauf, dass die gcloud CLI für die Verwendung des ausgewählten (oder erstellten) Projekts konfiguriert ist. Führen Sie den folgenden Befehl aus, um die konfigurierte Projekt-ID zu prüfen:
gcloud config get-value projectYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID]die ID des Projekts, das Sie ausgewählt oder erstellt haben.👉💻 Wenn Sie einen anderen Wert sehen, führen Sie den folgenden Befehl aus, um Ihre Projekt-ID als Standardprojekt-ID für gcloud CLI-Befehle zu konfigurieren:gcloud config set project [YOUR_PROJECT_ID]gcloud config set project lab-project-id-example-123
gcloud projects list \ --format='value(projectId)' \ --sort-by='~createTime'
- 👉💻 Legen Sie den Standort für die Bereitstellung von Ressourcen sowie die ID und Nummer Ihres Projekts in den Umgebungsvariablen fest:
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 Aktivieren Sie die für dieses Lab erforderlichen Google APIs.
gcloud services enable \ aiplatform.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ pubsub.googleapis.comOperation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.
3. ZooKeeper-Demoanwendung bereitstellen
In den folgenden Schritten werden Ressourcen bereitgestellt und konfiguriert, einschließlich der Bereitstellung der agentenbasierten KI-Anwendung.
Pub/Sub-Ressourcen einrichten
Sie erstellen zwei Pub/Sub-Themen. Eine wird vom Drittanbieterdienst verwendet, um Ereignisse an Ihre KI-Anwendung zu senden. Eine weitere für die Anwendung, um Ergebnisse der Ereignisverarbeitung zu veröffentlichen.
- 👉💻 Erstellen Sie ein Pub/Sub-Thema, mit dem die KI-Anwendung mit Agent-Funktionen ausgelöst wird:
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 Erstellen Sie ein Pub/Sub-Thema, in dem die Anwendung ihre Antworten posten kann:
gcloud pubsub topics create agent_responses export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)") gcloud pubsub subscriptions create agent_responses \ --topic=agent_responses
Dienstkonten und IAM-Richtlinien auf Projektebene einrichten
Sie erstellen zwei Dienstkonten, um den Zugriffsbereich des Cloud Run-Dienstes und des Eventarc-Triggers gemäß dem Prinzip der geringsten Berechtigung auf das Minimum zu beschränken. Der Cloud Run-Dienst benötigt Berechtigungen zum Schreiben von Logs und Traces, zum Aufrufen von Gemini LLM in Google Vertex AI und zum Posten von Ergebnissen in einem Pub/Sub-Thema. Für den minimalen Zugriff des Eventarc-Triggers sind Berechtigungen zum Aufrufen des Cloud Run ZooKeeper-Dienstes und zum Zugriff auf Pub/Sub zum Lesen der geposteten Ereignisse erforderlich. In dieser Anleitung erfahren Sie, wie Sie dem Dienstkonto des Triggers die Berechtigungen erteilen, die zum Übernehmen der Identität des Pub/Sub-Systemdienstes erforderlich sind. Nachdem Sie die Eventarc-Triggerressource erstellt haben, führen Sie den Befehl aus, mit dem die Rolle roles/run.invoker zugewiesen wird, damit das Dienstkonto des Triggers den Cloud Run-Dienst aufrufen kann.
- 👉💻 Dienstkonto für den Cloud Run-Dienst erstellen:
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Gewähren Sie dem Dienstkonto Berechtigungen zum Schreiben von Logs und Traces und zur Verwendung von Gemini-Modellen in Vertex AI:
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/logging.logWriter" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/cloudtrace.agent" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/aiplatform.user" \ --condition=None - 👉💻 Gewähren Sie dem Dienstkonto die Berechtigung, Nachrichten im Thema „agent_responses“ zu posten:
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 Dienstkonto für den Eventarc-Trigger erstellen:
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Gewähren Sie dem Pub/Sub-Systemdienstkonto Berechtigungen zum Senden authentifizierter Push-Anfragen:
gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
ZooKeeper-App in Cloud Run bereitstellen
Sie laden den Code der Demoanwendung von GitHub herunter. Stellen Sie den Code in Cloud Run bereit.
- 👉💻 Agentische KI-Anwendung herunterladen:
mkdir zoo-keeper-lab && cd zoo-keeper-lab git init git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos git config set core.sparseCheckout true echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout git pull origin main --depth 1 cd ai-ml/agent-labs/adk_invoke_with_pubsub/ - 👉💻 Agentische KI-Anwendung in Cloud Run bereitstellen:
gcloud run deploy zookeeper-agent \ --region="${LOCATION}" \ --source="." \ --no-allow-unauthenticated \ --quiet \ --service-account="${ZOOKEEPER_SA}" \ --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"
Eventarc-Trigger konfigurieren
Nachdem Sie alle Ressourcen (Pub/Sub-Themen, IAM-Dienstkonten und Cloud Run-Dienst) vorbereitet haben, können Sie die Eventarc-Triggerressource einrichten. Sie erstellen die Eventarc-Triggerressource und erteilen dem Dienstkonto des Triggers die Berechtigungen zum Aufrufen des Cloud Run-Dienstes.
- 👉💻 Eventarc-Trigger erstellen:
gcloud eventarc triggers create invoke-agent \ --location="${LOCATION}" \ --destination-run-service="zookeeper-agent" \ --destination-run-path="/zookeeper" \ --destination-run-region="${LOCATION}" \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic="${INVOKE_TOPIC_ID}" \ --service-account="${TRIGGER_SA}" - 👉💻 Berechtigungen für das Dienstkonto des Triggers zum Aufrufen des Cloud Run-Dienstes erteilen:
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
4. Wiederholung der Angaben zur Funktionsweise der Lösung
Sehen Sie sich nun an, was Sie gerade bereitgestellt haben. Das folgende Diagramm zeigt alle Ressourcen und wie sie miteinander interagieren. Sie verwenden die gcloud CLI, um eine Nachricht im Thema „invoke_agent“ zu veröffentlichen. Dadurch wird ein Ereignis simuliert, das ein Drittanbieterdienst im Messaging-Dienst protokolliert, um die KI-Anwendung aufzurufen.
Die Bereitstellung ist gemäß dem Prinzip der geringsten Berechtigung gesichert. Der Cloud Run-Dienst erzwingt die Authentifizierung (siehe das --no-allow-unauthenticated-Argument in Schritt 9 im vorherigen Abschnitt). Nur Identitäten mit der Rolle „roles/run.invoker“ oder ähnlichen Berechtigungen können den Dienst aufrufen. Diese Rolle wird nur dem Dienstkonto des Eventarc-Triggers gewährt. Ebenso wird der Zugriff auf das Thema „invoke_agent“ minimiert, um die unbefugte Veröffentlichung von Ereignissen zu verhindern. Es ist weiterhin möglich, den ZooKeeper-Agenten direkt aufzurufen, ohne Nachrichten im Pub/Sub-Thema zu posten. In Abschnitt 6 erfahren Sie, wie Sie den Endpunkt der Anwendung vor öffentlichem Zugriff verbergen.
Workflow ausführen
Sie simulieren ein externes Ereignis, indem Sie eine Frage in natürlicher Sprache in ZooKeeper veröffentlichen.
👉💻 Verwenden Sie den folgenden Befehl, um eine Nachricht im Pub/Sub-Thema zu posten:
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
In der Realität sind die Ereignisinformationen wahrscheinlich weniger gut lesbar. Damit eine KI-Anwendung mit Agentenfunktion das Ereignis verarbeiten kann, sind detaillierte Anweisungen zum Format des Ereignisses, zu den Daten und dazu erforderlich, was der Agent mit den Ereignisinformationen tun soll.
Sie können prüfen, ob der Agent das Ereignis empfangen, die Anfrage verarbeitet und die Antwort im Thema „agent_responses“ gepostet hat. Um die Antwort zu lesen, verwenden Sie das Abo „agent_responses“. Im Codelab wird dieselbe ID sowohl für das Thema als auch für das Abo für die Antworten verwendet.
👉💻 Verwenden Sie den folgenden Befehl, um die Antwort des Agents aus dem Pub/Sub-Abo zu lesen:
gcloud pubsub subscriptions pull agent_responses --auto-ack
In der Ausgabe wird eine Tabelle mit den Metadaten der Nachricht und der Nutzlast mit der Antwort angezeigt, dass es 33 Tierarten im Zoo gibt. Das Flag --auto-ack bestätigt die Nachricht automatisch, nachdem sie abgerufen wurde. Sie wird also nicht noch einmal zugestellt.
Funktionsweise
Den Quellcode der agentenbasierten KI-Anwendung finden Sie im Cloud Shell-Editor im Ordner ~/zoo-keeper-lab. Sie können sich den Quellcode auch auf GitHub ansehen.
- In main.py wird eine einfache FastAPI-Webanwendung mit einem einzelnen Handler implementiert, der Eventarc-Ereignisse verarbeitet.
- Die Datei processor.py parst die Nachricht des Ereignisses, um die Nutzer-ID und die Anfrage abzurufen. Anschließend wird eine neue Sitzung im ADK-Runner erstellt und der Zookeeper-Agent wird aufgerufen, um die Anfrage zu verarbeiten. Die Antwort des Agents wird im Pub/Sub-Thema „agent_responses“ veröffentlicht.
- Der Quellcode des ADK-Agents befindet sich im Unterordner zookeeper_agent. Sie können den Befehl
adk run zookeeper_agentüber den Stammordner der Anwendung ausführen, um mit dem Agent über die ADK-Befehlszeile zu interagieren.
Fehlerbehebung
Wenn einer der vorherigen Befehle fehlschlägt, lesen Sie die Fehlermeldung sorgfältig. Wenn die Bereitstellung in Cloud Run fehlschlägt, müssen Sie zuerst ermitteln, in welcher Phase des Prozesses der Fehler aufgetreten ist.
- Wenn in der Ausgabe des Befehls „gcloud run deploy...“ gemeldet wird, dass der Build fehlgeschlagen ist, sehen Sie sich die URL der Build-Logs in der Ausgabe an und öffnen Sie sie in einem separaten Fenster.
- Wenn in der Ausgabe etwas wie „Dienst konnte nicht gestartet werden“ oder Ähnliches steht, bedeutet das, dass der Dienst bereitgestellt wird, die Ausführung aber den Healthcheck nicht besteht. Öffnen Sie in diesem Fall den Log-Explorer oder lesen Sie den folgenden Absatz für den gcloud CLI-Befehl. Lesen Sie die Logs, um die Ursache des Fehlers zu ermitteln.
Was passiert, wenn Sie eine Nachricht in Pub/Sub gepostet haben, der Agent aber nicht antwortet oder die Antwort seltsam aussieht?
👉💻 Verwenden Sie den folgenden Befehl, um die Anwendungslogs zu lesen, die bei der letzten Ausführung gepostet wurden:
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
In den Logs wird die Ausführung aufgezeichnet und es werden Fehler wie eine falsche oder nicht parsierbare Nachrichtennutzlast, eine ungültige Antwort des Gemini-Modells, ungültige Umgebungseinstellungen und andere mögliche Probleme gemeldet.
5. Sicherheit der Bereitstellung erhöhen
Der bereitgestellte Cloud Run-Dienst stellt einen öffentlichen Endpunkt bereit, der von jedem im Internet aufgerufen werden kann. Der Endpunkt ist zwar vor unbefugten Aufrufen geschützt und die Struktur der Anfrage wird streng validiert, aber es bleibt dieser Angriffsvektor, der Denial-of-Service- und Denial-of-Wallet-Angriffe ermöglicht. Da der Dienst im aktuellen Design nur über den Eventarc-Trigger aufgerufen werden kann, muss sein Endpunkt nicht im Internet verfügbar sein.
👉💻 Schließen Sie diesen Angriffsvektor, indem Sie die Aufrufe des Dienstes auf die begrenzte Sammlung von Quellen beschränken, einschließlich Eventarc-Triggern:
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
Wenn Sie jetzt versuchen, die URL des Dienstes von Ihrem lokalen Computer aus aufzurufen, erhalten Sie den Fehler „404 Seite nicht gefunden“.
👉💻 Verwenden Sie curl, um eine Anfrage an den Dienstendpunkt zu senden:
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
Die Ausgabe sollte in etwa so aussehen:
<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>404 Page not found</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Page not found</h1> <h2>The requested URL was not found on this server.</h2> <h2></h2> </body></html>
Nach dieser Änderung ist es nicht mehr möglich, ZooKeeper direkt aufzurufen, indem Sie den Cloud Run-Dienstendpunkt aufrufen, es sei denn, Sie führen den Aufruf über die VPC im selben Projekt, das freigegebene VPC-Netzwerk, für das Ihre Revision konfiguriert ist, um Traffic zu senden, oder einen Host aus, der Teil des VPC Service Controls-Perimeters ist.
6. Zusammenfassung
Glückwunsch! Sie haben eine Umgebung eingerichtet, in der Ihre KI-Anwendung mit Agentenfunktionen asynchron aufgerufen wird, wenn eingehende Ereignisse ausgelöst werden.
Bereinigen
Wenn Sie die bereitgestellten Ressourcen behalten, können Gebühren für Ihr Rechnungskonto anfallen. Wenn Sie diese Umgebung nicht für weitere Tests verwenden möchten und zukünftige Gebühren vermeiden möchten, sollten Sie die Ressourcen löschen, die während dieses Codelabs erstellt wurden.
Dafür gibt es zwei Möglichkeiten:
Methode 1: Projekt beenden
Durch das Beenden (Löschen) des Projekts werden alle Ressourcen und Daten des Projekts freigegeben und das Rechnungskonto wird getrennt. Mit dieser Methode wird verhindert, dass für Ressourcen oder Daten, die für dieses Codelab verwendet werden, weitere Gebühren anfallen. Verwenden Sie den folgenden Befehl, um das Projekt herunterzufahren:
gcloud projects delete $(gcloud config get-value project) --quiet
Methode 2: Ressourcen im Projekt löschen
Wenn Sie den Cloud Run-Dienst löschen, fallen keine weiteren Gebühren für die Nutzung der serverlosen Plattform an. Hinweis: Bei dieser Methode werden nicht alle Daten, die während des Codelabs generiert wurden, vollständig entfernt, z. B. Cloud Build- und Anwendungslogs, Container-Images usw. Führen Sie den folgenden Befehl aus, um den Dienst zu löschen:
gcloud run services delete zookeeper-agent --region=${LOCATION}
Für die Eventarc-Triggerdefinition und Pub/Sub-Themen fallen keine Verwaltungskosten an. Weitere Informationen finden Sie unter Eventarc-Preise und Pub/Sub-Preise.
Weitere Informationen zum Beenden von Projekten
Nächste Schritte
- Weitere Informationen zum Code finden Sie in der Demo auf GitHub.
- Architektur für die Orchestrierung des Zugriffs auf unterschiedliche Unternehmenssysteme
- Cloud Run mit Eventarc-Triggern auslösen
- Weitere Informationen zum ADK