Agents in Agent Studio entwerfen

Auf dieser Seite erhalten Sie einen Überblick über die Verwendung von Agent Studio in derGoogle Cloud Console.

Agent Studio ist ein visueller Low-Code-Designer in der Google Cloud Konsole, der die Entwicklung von KI-Agenten vereinfacht. Sie können Agent-Arbeitsabläufe visuell darstellen, Antworten in Echtzeit testen und mit verschiedenen Konfigurationen experimentieren, bevor Sie den Code bereitstellen oder darauf umstellen.

In diesem Dokument finden Sie einen Überblick über Agent Studio. Außerdem wird beschrieben, wie Sie Ihre Umgebung einrichten, Agents erstellen und testen und sie direkt in einer Produktionslaufzeitumgebung bereitstellen.

Umgebung einrichten

Bevor Sie Agent Studio verwenden, müssen Sie Google Cloud einrichten.

Erforderliche Rollen abrufen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Agent Platform User (roles/aiplatform.user) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie für die Verwendung von Agent Studio 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.

Agent erstellen

Sie können einen Agent in Agent Studio mit Prompts oder dem Flow Builder erstellen.

KI‑Agenten mit Prompts erstellen

So erstellen Sie einen Agent mit Prompts:

  1. Rufen Sie in der Google Cloud Console die Seite Agents auf.

    Zu „KI-Agenten“

  2. Klicken Sie auf Agent erstellen, um die Arbeitsfläche von Agent Studio für einen neuen Agenten zu öffnen.

  3. Geben Sie im Chatfeld einen Prompt ein, der den Zweck und das beabsichtigte Verhalten Ihres Agenten beschreibt.

  4. Klicken Sie auf .

  5. Je nach Prompt passiert Folgendes:

    • Erfolgreich: Der Flow Builder wird sofort aktualisiert und zeigt die Live-Vorschau Ihres Agenten an. Im Chat wird eine Zusammenfassung der vorgenommenen Änderungen angezeigt. Alle Änderungen werden automatisch gespeichert.

    • Klarstellung erforderlich: Wenn Ihr Prompt mehrdeutig ist, stellt der Assistent im Chat eine klärende Frage, um besser zu verstehen, was Sie erstellen möchten.

    • Fehler:Wenn der Assistent Ihren Prompt nicht anwenden kann, werden Sie in einer Fehlermeldung aufgefordert, Ihre Anfrage neu zu formulieren.

  6. Sie können den Agent weiterhin mit Prompts oder dem Flow Builder aktualisieren.

  7. Klicken Sie in der Kopfzeile des Arbeitsbereichs auf Speichern, um den Agent zu speichern, und folgen Sie der Anleitung. Weitere Informationen finden Sie unter Agent speichern.

  8. Wenn Sie die Funktionen und Antworten des Agenten testen möchten, während Sie ihn erstellen, klicken Sie auf den Tab Vorschau und chatten Sie mit dem Agenten.

Beschränkungen

Beim Erstellen eines Agents mit Prompts gelten die folgenden Einschränkungen:

Funktion Beschränkung
Wissen Wissen kann einem Agent nicht hinzugefügt werden. Sie können die Benutzeroberfläche des Flow-Builders verwenden, um einem Agent Wissen hinzuzufügen.

Agent mit dem Flow Builder erstellen

So entwerfen und testen Sie einen Agent mit dem Flow Builder:

  1. Rufen Sie in der Google Cloud Console die Seite Agents auf.

    Zu „KI-Agenten“

  2. Klicken Sie auf Agent erstellen, um die Arbeitsfläche von Agent Studio für einen neuen Agenten zu öffnen.

  3. Sie können Ihren Agenten im Arbeitsbereich von Agent Studio entwerfen und speichern. Sie können zwischen den folgenden Tabs wechseln:

    • Ablauf:Erstellen Sie den Haupt- und die Sub-Agents mithilfe einer visuellen Darstellung des Workflows und der Steuerungslogik Ihres Agenten.

      1. Klicken Sie auf einen KI-Agenten, um den Bereich Details für diesen KI-Agenten zu öffnen. Sie können auch auf Untervertreter hinzufügen (+) klicken, um Untervertreter hinzuzufügen.

      2. Konfigurieren Sie Ihren Haupt- und Ihre Subagenten im Bereich Details:

      3. Name:Geben Sie einen Namen ein, mit dem sich der Agent identifizieren lässt.

      4. Beschreibung:Eine Zusammenfassung des Zwecks Ihres Agents.

      5. Anleitung:Fügen Sie eine Anleitung hinzu, um Ihren Agenten zu steuern.

      6. Modell:Wählen Sie das Modell aus, das Ihren Agent unterstützen soll.

        1. Tools:Klicken Sie auf Tools hinzufügen (+), um Tools hinzuzufügen, mit denen der Agent Aufgaben erledigen kann. Weitere Informationen finden Sie unter Tools einrichten und hinzufügen.

      7. Klicken Sie in der Kopfzeile des Arbeitsbereichs auf Speichern, um den Agent zu speichern, und folgen Sie der Anleitung. Weitere Informationen finden Sie unter Agent speichern.

    • Tab „Vorschau“:Chatten Sie im Vorschaufenster mit Ihrem Agenten, um seine Funktionen und Antworten zu testen.

  4. Klicken Sie auf Code abrufen, um Ihren Agent-Code aufzurufen. Wenn Sie Ihren Agenten an anderer Stelle weiterentwickeln möchten, können Sie den Code kopieren und in einen Code-Editor Ihrer Wahl einfügen.

Wenn Ihr Agent fertig ist, können Sie ihn direkt über Agent Studio bereitstellen. Weitere Informationen finden Sie unter Agent über Agent Studio bereitstellen.

Agent-Ereignisse prüfen

Wenn Sie Ereignisse untersuchen, können Sie das Verhalten Ihres KI-Agenten debuggen und den Denkprozess und die Modellanfragen Ihres KI-Agenten nachvollziehen.

Sie können die Ausführung von KI-Agenten debuggen, indem Sie sich die Agent-Ereignisse auf dem Tab Vorschau in Agent Studio ansehen. Mit dieser Aktion können Sie Probleme in den einzelnen Ereignissen diagnostizieren, die der Agent während eines Laufs erzeugt.

So prüfen Sie Agent-Ereignisse:

  1. Öffnen Sie Ihren Agent im Agent Studio-Canvas und dann den Tab Vorschau.
  2. Starten Sie im Vorschaufenster einen Chat mit Ihrem KI-Agenten, um einen Lauf zu starten.

  3. Wählen Sie ein Ereignis in der Unterhaltung aus, um die zugehörigen Details zu öffnen. Die verfügbaren Details hängen vom Ereignis ab und können Folgendes umfassen:

    • Autor:Der Agent oder Unteragent, der das Ereignis erstellt hat. Mit dem Autor können Sie ermitteln, welcher Sub-Agent einen Schritt in einem Workflow mit mehreren Agenten ausgeführt hat.
    • Anfrage und Antwort:Die an das Modell gesendete Nutzlast und die zurückgegebene Antwort.
    • Toolaufrufe:Die Argumente, die während der Ausführung des Agenten an Tools übergeben werden.
    • Metadaten:Zusätzliche Diagnoseinformationen wie Modellname, Tokennutzung und Zeitstempel.

Wenn der KI-Agent während der Vorschau einen Fehler zurückgibt, wird der Fehler auf dem Tab Vorschau angezeigt, damit Sie das Problem diagnostizieren können.

KI-Agent speichern

Sie müssen einen Agent speichern, bevor Sie ihn in der Vorschau ansehen, bereitstellen oder Wissensdateien hochladen können, da ein nicht gespeicherter Agent noch keine Identität hat. So speichern Sie einen Agenten zum ersten Mal:

  1. Klicken Sie im Canvas von Agent Studio auf Speichern.

  2. Geben Sie im Dialogfeld KI-Agent speichern einen KI-Agentenname ein.

  3. Klicken Sie auf Speichern.

Nach dem ersten Speichern werden alle weiteren Änderungen, die Sie vornehmen, automatisch in Agent Studio gespeichert. Wenn Sie versuchen, den Arbeitsbereich zu verlassen, bevor Sie einen neuen Agent gespeichert haben, werden Sie in Agent Studio aufgefordert, ihn zuerst zu speichern.

KI-Agenten aktualisieren

So aktualisieren Sie einen Agenten:

  1. Rufen Sie in der Google Cloud Console die Seite Agents auf.

    Zu „KI-Agenten“

  2. Klicken Sie beim Agenten, den Sie aktualisieren möchten, auf  und dann auf Bearbeiten.

  3. Aktualisieren Sie den Agenten mit Prompts oder dem Flow Builder.

Ihre Änderungen werden in Agent Studio automatisch gespeichert.

Tools in Agent Studio einrichten und hinzufügen

Sie können die folgenden Tools für Ihren Agenten konfigurieren:

  • Google Suche:Ermöglicht es dem Agenten, Websuchen über die Google Suche durchzuführen. Standardmäßig aktiviert.

  • URL-Kontext:Ermöglicht dem Modell, URLs aus Prompts zu analysieren, die an den Agent gesendet werden. Standardmäßig aktiviert.

  • Agent Search-Datenspeicher:Klicken Sie auf Hinzufügen (+), damit Ihr KI-Agent auf Informationen zugreifen kann, die in Ihrem Agent Search-Datenspeicher indexiert wurden.

    Wenn Sie noch keinen Datenspeicher haben, erstellen Sie einen. Gewähren Sie dann dem Dienstkonto Zugriff auf Agent Search:

    1. Rufen Sie in der Google Cloud Console die Seite IAM auf.

      Zur Identitäts- und Zugriffsverwaltung (IAM)

    2. Klicken Sie auf Zugriff erlauben.

    3. Geben Sie im Feld Neue Hauptkonten die folgenden Informationen zum Dienstkonto ein:

      service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

    4. Wählen Sie + Rollen hinzufügen aus. Suchen Sie nach Discovery Engine User und wählen Sie diese Option aus. Klicken Sie auf Anwenden und dann auf Speichern.

  • MCP-Server:Stellen Sie eine direkte Verbindung zu einem MCP-Server (Model Context Protocol) her.

    1. Wenn Sie MCP-Tools hinzufügen möchten, indem Sie eine Verbindung zu einem MCP-Server herstellen, klicken Sie neben MCP-Server auf Hinzufügen (+).
    2. Anzeigename für das MCP:Geben Sie einen Namen für Ihren MCP-Server ein.
    3. Endpunkt-URL:Geben Sie eine Endpunkt-URL für den MCP-Server ein.
    4. Authentifizierung:Autofill-Wert Keine. Agent Studio unterstützt nur MCP-Server, für die keine Authentifizierung erforderlich ist.

    Ihr Agent kann alle Tools auf Ihrem verbundenen MCP-Server verwenden.

KI‑Agenten mit Wissensdateien verknüpfen

So laden Sie statische Referenzdokumente hoch, auf denen die Antworten Ihres Agents in Agent Studio basieren:

  1. Wählen Sie den übergeordneten Agent-Knoten im Arbeitsbereich aus, an den Sie Referenzdateien anhängen möchten. Wissensdateien können nicht an Sub-Agents angehängt werden.
  2. Suchen Sie im Bereich Details des Knotens den Abschnitt Wissen. Der Bereich Wissen wird erst angezeigt, nachdem Sie den Agenten zum ersten Mal gespeichert haben. Weitere Informationen finden Sie unter Agent speichern.
  3. Klicken Sie auf die Komponente zum Hochladen von Dateien und wählen Sie die Referenzdatei aus. Sie können bis zu 10 Dateien pro KI‑Agent anhängen. Die Datei darf nicht größer als 2 MB sein. Die Upload-Oberfläche unterstützt die folgenden Dateitypen:
    • PDF
    • Nur-Text

  4. Klicken Sie in der Kopfzeile des Arbeitsbereichs auf Speichern, um Dateien in einem dedizierten Cloud Storage-Bucket unter einem Pfadpräfix zu speichern, das mit dem AGENT_ID des übergeordneten Agents übereinstimmt.

    Im Berechtigungsdialog wird der Identität des Agents die Rolle „Storage-Objekt-Betrachter“ (roles/storage.objectViewer) für den Bucket zugewiesen.

  5. Rufen Sie den Tab Vorschau auf und senden Sie eine Testanfrage, um zu prüfen, ob der KI-Agent seine Antwort auf den Inhalt der Datei stützt, ohne zu halluzinieren.

  6. Optional: Sie können auf Code abrufen klicken, um den generierten Python-Code zu kopieren (agent.py) und die Konfiguration der Grounding-Datei zu prüfen. Dann können Sie diesen Schritt überspringen.

Berechtigungen für die Agent-Identität verwalten

Jeder Agent in Agent Studio hat eine eindeutige Identität, die als IAM-Hauptkonto für den Zugriff auf andere Google Cloud Ressourcen dient.

Das Hauptformat ist:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

Ersetzen Sie Folgendes:

  • ORGANIZATION_ID: die numerische ID Ihrer Organisation.
  • PROJECT_NUMBER: die Projektnummer IhresGoogle Cloud -Projekts.
  • LOCATION: die Region, in der Ihr Agent bereitgestellt wird.
  • REASONING_ENGINE_ID: Die Ressourcen-ID Ihrer Reasoning Engine.

Weitere Informationen zu Agent-Identitäten finden Sie unter Agent mit Agent-Identität erstellen und Übersicht über Agent-Identitäten.

Verhalten des Berechtigungsdialogfelds

Wenn Sie auf Bereitstellen klicken oder den Tab Vorschau für einen gespeicherten Agent öffnen, prüft Agent Studio automatisch, ob die Identität des Agents die erforderlichen IAM-Rollen für eine erfolgreiche Ausführung hat. Fehlende oder fehlerhaft konfigurierte Berechtigungen können dazu führen, dass Ihr KI-Agent nicht funktioniert. Wenn Sie der Identität des KI-Agenten diese Berechtigungen erteilen, hilft dies dabei, dass er erwartungsgemäß funktioniert.

Wenn das System Berechtigungsprobleme erkennt, wird im Berechtigungsdialogfeld eine Fehlermeldung angezeigt.

  • Fehlende Rollen:Wenn erforderliche Rollen fehlen, wird ein Dialogfeld mit den detaillierten Rollen angezeigt. Klicken Sie im Dialogfeld auf Alle gewähren, um der Identität des Agents automatisch alle erforderlichen Rollen in einem einzigen Schritt zuzuweisen. Wenn Sie eine Vorschau des Agents ansehen oder ihn bereitstellen möchten, ohne die Rollen zu gewähren, klicken Sie auf Trotzdem fortfahren.
  • Alle Rollen gewährt:Wenn alle erforderlichen Rollen bereits gewährt wurden, wird das Berechtigungsdialogfeld nicht angezeigt.
  • Nicht gespeicherte Agents:Nicht gespeicherte Agents haben noch keine Identität. Das Berechtigungsdialogfeld wird nicht angezeigt und die Optionen Vorschau und Bereitstellen sind deaktiviert, bis Sie den Agenten speichern.

Erforderliche Rollen

Im Berechtigungsdialog werden automatisch die folgenden Rollen gewährt:

  • roles/storage.objectViewer: Erforderlich, wenn der Agent hochgeladene Dateien verwendet. Diese Rolle muss für den jeweiligen Cloud Storage-Bucket für Agent-Dateien (z. B. {projectNumber}_{location}_agent_studio_files) gewährt werden.
  • roles/mcp.toolUser: Erforderlich, wenn der Agent ein MCP-Tool der Agent Registry verwendet.
  • roles/agentregistry.viewer: Erforderlich, wenn der Agent ein MCP-Tool oder einen untergeordneten Agenten aus der Agent Registry verwendet.
  • roles/iamconnectors.user: Erforderlich, wenn für ein MCP-Tool der Agent Registry ein authProviderName angegeben ist.
  • roles/aiplatform.viewer: Erforderlich, wenn der Agent Remote-Unter-Agents über die Agent-to-Agent-Delegierung (A2A) aufruft.

Rollen manuell in der Google Cloud Console verwalten

Im Berechtigungsdialog werden erforderliche Rollen automatisch gewährt. Wenn Sie Rollen lieber manuell verwalten oder Berechtigungsprobleme beheben möchten, gehen Sie so vor:

  1. Kopieren Sie den eindeutigen Identitätsprinzipal des Agents. Klicken Sie in der Kopfzeile des Agent Studio-Arbeitsbereichs auf das Drop-down-Menü neben dem Agent-Namen und kopieren Sie den Prinzipal-String.

    Das Hauptformat sieht so aus:

    principal://agents.global.org-ORG_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

  2. Rufen Sie in der Google Cloud Console IAM auf:

    IAM aufrufen

  3. Suchen Sie in der Prinzipliste nach dem Prinzipal der Identität des KI-Agents. Sie können nach der spezifischen REASONING_ENGINE_ID am Ende der Prinzipalzeichenfolge suchen. Sie haben eine der folgenden Optionen, um den Prinzipal der Agent-Identität abzurufen:

    • Wenn das Prinzipal der Identität des KI-Agents bereits aufgeführt ist, klicken Sie neben der Identität des KI-Agents auf  Prinzipal bearbeiten.
    • Wenn das Hauptkonto für die Identität des Agents nicht aufgeführt ist, klicken Sie auf Zugriff gewähren, um es als neues Hauptkonto hinzuzufügen.

  4. Fügen Sie die erforderlichen Rollen für Ihre Konfiguration hinzu oder ändern Sie sie, z. B. roles/storage.objectViewer oder roles/mcp.toolUser.

  5. Klicken Sie auf Speichern.

Je nach Konfiguration müssen Sie möglicherweise zusätzliche Rollen manuell zuweisen, die im Berechtigungsdialog nicht automatisch berücksichtigt werden. Wenn Ihr registriertes MCP-Tool beispielsweise auf andere Google Cloud Ressourcen zugreift, z. B. Daten aus BigQuery abfragt, müssen Sie der Identität des Agents manuell die erforderlichen Rollen zuweisen, z. B. die Rolle „BigQuery-Datenbetrachter“ (roles/bigquery.dataViewer).

Agent aus Agent Studio bereitstellen

Nachdem Sie einen Agent erstellt und in der Vorschau angesehen haben, können Sie ihn in der Produktion bereitstellen. So stellen Sie einen Agenten über Agent Studio bereit:

  1. Klicken Sie auf der Listenseite Agents auf den Agent, den Sie bereitstellen möchten. Die Seite mit den Agent-Details für den ausgewählten Agent wird angezeigt.

  2. Klicken Sie auf Bereitstellen, um das Dialogfeld In einer Agent Runtime-Instanz bereitstellen zu öffnen.

    Wenn der Identität des Agents erforderliche Berechtigungen fehlen, wird das Berechtigungsdialogfeld angezeigt und diese Aktion wird automatisch ausgeführt. Wenn Sie Berechtigungen manuell verwalten müssen, lesen Sie die Informationen unter Berechtigungen für die Identität von Agents verwalten und Zugriff für die Agent-zu-Agent-Delegierung (A2A) gewähren.

  3. Konfigurieren Sie im Fenster für die Bereitstellungskonfiguration die folgenden Optionen:

    • Anzeigename und Beschreibung: Bearbeiten Sie den Anzeigenamen und fügen Sie optional eine Beschreibung für Ihren Agent hinzu.
    • Als A2A bereitstellen: Wählen Sie dieses Kästchen aus, um den Agenten als Agent-to-Agent-Asset (A2A) bereitzustellen, das von anderen Agenten wiederverwendet werden kann. Lassen Sie das Kästchen für eigenständige Anwendungen deaktiviert, um den Agent als Standard-ADK-Anwendung zu verpacken.

  4. Wählen Sie eine Bereitstellungsregion aus der Liste der verfügbaren Regionen aus und klicken Sie auf OK.

  5. Klicken Sie auf Bereitstellen.

Bei der Bereitstellung wird eine neue Laufzeitinstanz erstellt. Das kann bis zu fünf Minuten dauern. Bei Erfolg wird eine Meldung auf dem Tab Flow des Agent Studio-Arbeitsbereichs angezeigt. Ihr Agent ist jetzt in der Produktion verfügbar und kann sicher in Ihre externen Apps eingebunden werden.

Bereitgestellten KI-Agenten ansehen

So rufen Sie Ihren bereitgestellten KI-Agenten auf:

  1. Rufen Sie in der Google Cloud Console die Seite Deployments der Agent-Plattform auf.

    Zu Deployments

  2. Verwenden Sie die Liste Region, um nach Bereitstellungsregion zu filtern.

  3. Bereitgestellte Agents, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt.

  4. Klicken Sie auf den Namen des angegebenen Agents. Die Seite Messwerte für den Agenten wird geöffnet.

  5. Wählen Sie den Tab Playground aus, um den Agent zu testen.

  6. Geben Sie eine Testanfrage in den Chatbereich ein, um zu prüfen, ob der Agent ordnungsgemäß ausgeführt wird.

Weitere Informationen zu den verfügbaren Messwerten für Ihren Agenten finden Sie unter Messwerte für Ihren bereitgestellten Agenten ansehen.