Integration mit einem KI-Agenten erstellen

Auf dieser Seite erfahren Sie, wie Sie eine Integration erstellen, indem Sie einen KI-Codierungs-Agenten auffordern. Sie beschreiben, was die Integration tun soll, und der Agent schreibt die Integration, lädt sie hoch und veröffentlicht sie mit der Application Integration REST API, führt sie aus und hilft Ihnen bei der Fehlerbehebung. Als Beispiel erstellen Sie eine einfache Integration für die Schadensregulierung.

Der KI-Agent bezieht sein Wissen über Application Integration aus drei öffentlichen Agent-Skills im Repository google/skills:

Die Referenzdateien für die einzelnen Skills finden Sie unter Application Integration-Agent-Skills.

Hinweis

  1. Verwenden Sie ein Google Cloud -Projekt, in dem Sie sicher experimentieren können, kein Produktionsprojekt. Die Abrechnung muss für das Projekt aktiviert sein.
  2. Richten Sie Application Integration im Projekt in einer unterstützten Region ein. Für die Einrichtung von Application Integration sind eigene Rollen erforderlich, die auf dieser Seite aufgeführt sind.
  3. Installieren Sie die gcloud CLI und melden Sie sich mit gcloud auth login an. Der KI-Agent ruft die REST API in Ihrem Namen mit Ihren gcloud-Anmeldedaten oder, wenn er eine Clientbibliothek verwendet, mit Standardanmeldedaten für Anwendungen auf. Wenn der Agent eine Clientbibliothek verwendet, werden Sie möglicherweise aufgefordert, gcloud auth application-default login auszuführen.
  4. Verwenden Sie einen KI-Programmieragenten, der Agenten-Skills unterstützt.

Erforderliche Rollen

Nachdem Application Integration eingerichtet wurde, benötigen Sie die folgenden Rollen, um Integrationen zu erstellen und auszuführen.

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Hochladen, Veröffentlichen und Ausführen von Integrationen und zum Aufrufen ihrer Ausführungen benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Informationen dazu, wer die Rolle „Dienstkontonutzer“ benötigt und wie sie zugewiesen wird, finden Sie unter Rolle „Dienstkontonutzer“ für „Ausführen als“-Dienstkonten zuweisen.

Agenten-Skills installieren

Führen Sie im Terminal die folgenden Befehle aus, um die drei Skills zu installieren:

npx skills add google/skills --skill application-integration-basics
npx skills add google/skills --skill application-integration-authoring
npx skills add google/skills --skill application-integration-troubleshooting

Wählen Sie bei Aufforderung die zu konfigurierenden Agents und den Installationsumfang aus. Wenn Ihr Agent nicht aufgeführt ist, wird die Standardoption „Universal“ in .agents/skills installiert. Das Installationsprogramm bietet möglicherweise auch andere Fähigkeiten, z. B. find-skills. Diese benötigen Sie für diese Seite nicht. Einige Agenten laden Skills aus einem Projektordner erst, nachdem Sie diesen Ordner als vertrauenswürdig eingestuft haben. Wenn npx nicht verfügbar ist, installieren Sie Node.js, das es enthält. Wenn Sie die Skills später aktualisieren möchten, führen Sie npx skills update aus.

Integration beschreiben

Starten Sie Ihren Agenten in einem leeren Arbeitsverzeichnis und beschreiben Sie die Integration. Geben Sie den Trigger, die Ein- und Ausgaben, die Regeln und den Bereitstellungsort genau an. Beispiel:

Using the Application Integration skills, build an integration named
claims-adjudication in project PROJECT_ID, region LOCATION.

- Start it with an API trigger named adjudicate_claim.
- Inputs: claimId (string), claimAmount (double), policyActive (boolean).
- Outputs: decision (string) and reason (string).
- Rules: if policyActive is false, return DENY. If claimAmount is 1000 or less,
  return APPROVE. Otherwise, return REVIEW. Set reason to a short explanation.
- Save the integration version JSON in this directory so I can review it.
- Show me every command before you run it, then upload, publish, and run it
  once with a sample claim.

Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID und LOCATION durch die Region, in der Sie Application Integration eingerichtet haben.

Plan prüfen und Befehle genehmigen

Der Agent schreibt eine Integrationsversionsdatei, z. B. claims-adjudication.json. Sie enthält den Trigger (triggerConfigs), die Aufgaben (taskConfigs) und die Variablen (integrationParameters). Lesen Sie sie, bevor Sie fortfahren, und bitten Sie den Agenten, alles zu erklären, was Sie nicht erwarten. Prüfen Sie beispielsweise, ob der Agent Cloud Logging (cloudLoggingDetails.enableCloudLogging) aktiviert hat, was zu zusätzlichen Kosten führen kann. Wenn Sie die Funktion deaktivieren möchten, setzen Sie enableCloudLogging auf false und entfernen Sie cloudLoggingSeverity.

Die Skills weisen den KI-Agenten an, frei Lesezugriff-Prüfungen auszuführen, z. B. Integrationen oder Ausführungen aufzulisten, aber den genauen Befehl oder die genaue Anfrage anzuzeigen und auf Ihre Genehmigung zu warten, bevor Änderungen vorgenommen werden. Dazu gehören das Aktivieren von APIs, das Ändern von IAM-Richtlinien sowie das Hochladen, Veröffentlichen oder Ausführen einer Integration. Wenn der KI-Agent um Genehmigung bittet, ohne den genauen Befehl oder die genaue Anfrage anzuzeigen, bitten Sie ihn, diese anzuzeigen. In den Berechtigungseinstellungen Ihres KI-Agenten werden Sie möglicherweise auch aufgefordert, jeden Befehl zu genehmigen, einschließlich Befehlen mit Lesezugriff. Prüfen Sie das Projekt, die Region und den Integrationsnamen in jedem Befehl, bevor Sie ihn genehmigen.

Integration hochladen, veröffentlichen und ausführen

Nachdem Sie die Genehmigung erteilt haben, führt der KI-Agent die folgenden Application Integration API-Aufrufe aus:

  1. versions.upload lädt die JSON-Datei als neue Version der Integration hoch.
  2. versions.publish veröffentlicht diese Version. Eine veröffentlichte Version ist ACTIVE und alle zuvor veröffentlichten Versionen werden zurückgezogen.
  3. integrations.execute führt die veröffentlichte Integration synchron über ihren API-Trigger aus.

Sie können die veröffentlichte Integration auch selbst ausführen:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "triggerId": "api_trigger/adjudicate_claim",
      "inputParameters": {
        "claimId": {"stringValue": "CLM-1001"},
        "claimAmount": {"doubleValue": 2500},
        "policyActive": {"booleanValue": true}
      }
    }' \
    "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/claims-adjudication:execute"

Die Antwort enthält eine executionId und die Ausgabevariablen der Integration in outputParameters.

Ausführung prüfen und Fehler beheben

Eine erfolgreiche Antwort von integrations.execute bedeutet nicht immer, dass jede Aufgabe wie erwartet ausgeführt wurde. Mit der Wiederholungsstrategie einer Aufgabe kann die Ausführung nach dem Fehlschlagen der Aufgabe fortgesetzt werden: Mit Ignorieren wird die fehlgeschlagene Aufgabe von der Integration als erfolgreich behandelt und mit Keine kann die Integration über einen alternativen Pfad trotzdem als erfolgreich abgeschlossen werden. Wenn in einer Anfrage doNotPropagateError auf true gesetzt ist, werden Fehler in der Antwort zurückgegeben, nicht als Fehlerstatus. Bitten Sie den KI-Agenten, die Ausführung zu prüfen, z. B.:

Check execution EXECUTION_ID of claims-adjudication. Did every task
succeed? If anything failed, tell me why and propose a fix.

Der Agent liest den Ausführungsdatensatz mit der Methode executions.list, gefiltert nach Ausführungs-ID:

curl -G \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode 'filter=execution_id="EXECUTION_ID"' \
    "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/claims-adjudication/executions"

Der Eintrag enthält den Ausführungsstatus, z. B. SUCCEEDED, FAILED oder SUSPENDED, sowie den Status der einzelnen Aufgaben. Sie können die Ausführungsprotokolle auch in der Google Cloud Console öffnen. Cloud Logging ist für Integrationen standardmäßig deaktiviert. Informationen zur Verwendung finden Sie unter Integrationslogs in Cloud Logging ansehen.

Wenn du eine Korrektur anwendest, wird eine neue Version hochgeladen und veröffentlicht. Daher wird der Agent durch die Skills angewiesen, dich zuerst noch einmal um Genehmigung zu bitten. Nach der Veröffentlichung kann die vorherige Version noch bis zu 10 Minuten lang ausgeführt werden. Warten Sie also, bevor Sie die Korrektur testen. Durch das Veröffentlichen werden auch die gesperrten Ausführungen der vorherigen Version abgebrochen, z. B. Ausführungen, die auf eine Genehmigung warten.

Best Practices

  • Beginnen Sie außerhalb der Produktion. Erstellen und testen Sie die JSON-Datei in einem Nicht-Produktionsprojekt und übertragen Sie sie dann. Siehe Integrationen hochladen und herunterladen.
  • Verwenden Sie ein dediziertes „Ausführen als“-Dienstkonto. Verwenden Sie für jede Integration ein dediziertes Dienstkonto mit minimalem Umfang. Weitere Informationen finden Sie unter Dienstkonto für die Ausführung festlegen.
  • Secrets nicht in Konfigurationsvariablen speichern Konfigurationsvariablen werden als Nur-Text gespeichert und exportiert. Verwenden Sie stattdessen ein Authentifizierungsprofil oder die Secret Manager-Zugriffsaufgabe.
  • Prüfen Sie den generierten JSON-Code. Behalten Sie sie in der Versionsverwaltung und prüfen Sie die Änderungen, bevor Sie sie hochladen. Authentifizierungsprofile sind nicht in der Datei enthalten. Konfigurieren Sie sie daher in jedem Projekt.

Bereinigen

Wenn Sie die Beispielintegration entfernen möchten, fragen Sie den KI-Agenten:

Unpublish claims-adjudication, then delete every version of it.

Nachdem Sie die Genehmigung erteilt haben, ruft der Agent versions.unpublish für die veröffentlichte Version und versions.delete für jede Version auf. Wenn keine Versionen mehr vorhanden sind, wird die Integration nicht mehr in der Liste der Integrationen angezeigt. Zum Löschen der Integration selbst ist eine Rolle wie „Application Integration Admin“ erforderlich. Mit der Rolle „Bearbeiter“ ist das nicht möglich.

Nächste Schritte