Einige Produkte und Funktionen werden umbenannt. Außerdem werden die Funktionen für generative Playbooks und Flows zu einer einzigen konsolidierten Konsole migriert.

Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Playbook-Tools

Mit Tools können Sie Playbooks mit externen Systemen verbinden. Diese Systeme können das Wissen von Playbooks erweitern und sie in die Lage versetzen, komplexe Aufgaben effizient auszuführen.

Sie können integrierte Tools verwenden oder benutzerdefinierte Tools erstellen, die Ihren Anforderungen entsprechen.

Tooltests

Nachdem Sie ein Tool erstellt haben, können Sie mit der Tool-Testfunktion prüfen, ob es funktioniert. Klicken Sie beim Ansehen eines Tools auf den Button Testen über dem Toolbereich. Dadurch wird das Tool für die Eingabe im Simulator geöffnet. Geben Sie die Eingabe für das Tool ein und klicken Sie dann auf Ausgabe ansehen, um die korrekte Ausgabe des Tools zu prüfen.

Sie können die Funktion zum Testen von Tools auch verwenden, wenn Sie einem Beispiel ein Tool hinzufügen.

Integrierte Tools

Integrierte Tools werden von Google gehostet. Sie können diese Tools in Agenten aktivieren, ohne dass eine manuelle Konfiguration erforderlich ist.

Folgende integrierte Tools werden unterstützt:

Code Interpreter: Ein Google-Tool, das die Funktionen der Codegenerierung und Code-Ausführung kombiniert und Ihnen ermöglicht, verschiedene Aufgaben auszuführen, darunter Datenanalyse, Datenvisualisierung, Textverarbeitung und das Lösen von Gleichungen oder Optimierungsproblemen.

Ihr Agent ist so optimiert, dass er bestimmt, wie und wann diese Tools aufgerufen werden sollen. Sie können jedoch zusätzliche Beispiele für Ihre Anwendungsfälle bereitstellen.

Beispielschema:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/df-code-interpreter-tool",
    "action": "generate_and_execute",
    "inputParameters": [
      {
        "name": "generate_and_execute input",
        "value": "4 + 4"
      }
    ],
    "outputParameters": [
      {
        "name": "generate_and_execute output",
        "value": {
          "output_files": [
            {
              "name": "",
              "contents": ""
            }
          ],
          "execution_result": "8",
          "execution_error": "",
          "generated_code": "GENERATED_CODE"
        }
      }
    ]
  }
}

OpenAPI-Tools

Ein Agent kann sich über ein OpenAPI-Tool mit einer externen API verbinden, wenn das OpenAPI-Schema bereitgestellt wird. Standardmäßig ruft der Agent die API in Ihrem Namen auf.

Mit der Funktion „Tool testen“ auf der Toolseite können Sie prüfen, ob das Tool richtig eingerichtet ist. Diese Funktion ist auch in der Beispielansicht verfügbar, wenn Sie dem Beispiel einen Toolaufruf hinzufügen.

Alternativ können Sie OpenAPI-Tools auf der Clientseite ausführen.

Beispielschema:

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: Dialogflow session id
          required: false
          schema:
            $ref: "@dialogflow/sessionId"
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

Sie können die interne Schemareferenz @dialogflow/sessionId als Parameterschematyp verwenden. Bei diesem Parameterschematyp wird die Dialogflow CX-Sitzungs-ID für die aktuelle Unterhaltung als Parameterwert angegeben.

Beispiel:

- name: X-SESSION
   in: header
   description: Dialogflow session id
   required: false
   schema:
     $ref: "@dialogflow/sessionId"

Einschränkungen von OpenAPI-Tools

Es gelten folgende Einschränkungen:

Die unterstützten Parametertypen sind path, query und header. Der Parametertyp cookie wird nicht unterstützt.
Durch das OpenAPI-Schema definierte Parameter unterstützen die folgenden Datentypen: string, number, integer, boolean und array. Der Typ object wird nicht unterstützt.
Im Beispiel-Editor der Console können Sie keine Abfrageparameter angeben.
Der Anfrage- und Antworttext muss leer sein oder das Format application/json verwenden.

OpenAPI-Tool-Schemagenerierung

Wenn Sie ein Schema angeben, klicken Sie auf Gemini verwenden, um Ihr Schema mithilfe von generativer KI zu erstellen.

Geben Sie die folgenden Details an, um die Generierung zu steuern:

Eine Anfrage-URL.
Eine HTTP-Methode, z. B. GET oder POST.
Beispieleingabe.
Beispielausgabe:
Ein Text-Prompt, der das Tool beschreibt.

Nachdem Sie das Schema generiert haben, können Sie es nach Bedarf bearbeiten und zusätzliche URLs und Methoden manuell hinzufügen.

API-Authentifizierung für OpenAPI-Tools

Sie können die folgenden Authentifizierungsoptionen verwenden, wenn Sie eine externe API aufrufen.

Authentifizierung des Dialogflow CX-Dienst-Agents

Dialogflow CX kann mithilfe des Dialogflow CX-Dienst-Agents ein ID-Token generieren. Das Token wird im HTTP-Header für die Autorisierung hinzugefügt, wenn Dialogflow CX eine externe API aufruft.

Sie können ein ID-Token verwenden, um auf Cloud Run-Funktionen und Cloud Run-Dienste zuzugreifen, nachdem Sie service-agent-project-number@gcp-sa-dialogflow. die Rollen roles/cloudfunctions.invoker und roles/run.invoker zugewiesen haben.

Wenn sich die Cloud Run Functions-Funktionen und Cloud Run-Dienste im selben Ressourcenprojekt befinden, benötigen Sie keine zusätzlichen IAM-Berechtigungen (Identity and Access Management), um sie aufzurufen.

Dienstkonto-Authentifizierung

Dienstkonten können Toolanfragen an alle Google APIs authentifizieren, die dies unterstützen.

Erstellen Sie ein Dienstkonto, falls noch nicht geschehen. Da es sich bei Dienstkonten um Hauptkonten handelt, können Sie ihnen Rollen für den Zugriff auf Ressourcen in Ihrem Projekt zuweisen, wie Sie es auch für jedes andere Hauptkonto tun würden. Sie können die E-Mail-Adresse des Dienstkontos verwenden, um ein Zugriffstoken zu generieren, das Sie im Authorization-Header der Toolanfrage senden.

Wenn Sie das Tool für die Verwendung von Dienstkonten konfigurieren, benötigen Sie die folgenden Berechtigungen:

roles/iam.serviceAccountUser

Damit Dialogflow CX Tokens generieren kann, weisen Sie dem Dialogflow CX-Dienst-Agenten die folgenden Berechtigungen zu:

roles/iam.serviceAccountTokenCreator

Das Dienstkonto muss außerdem Berechtigungen für den Zugriff auf den Dienst haben, der das Tool hostet.

Authentifizierung von API-Schlüsseln

Sie können die API-Schlüsselauthentifizierung konfigurieren, indem Sie den Schlüsselnamen, den Speicherort der Anfrage (Header oder Abfragestring) und den API-Schlüssel angeben, damit Dialogflow CX den API-Schlüssel in der Anfrage übergibt.
Wir empfehlen, den API-Schlüssel über Secret Manager bereitzustellen.
Nach dem 15. August 2025 enthalten exportierte Agenten keine API-Schlüssel mit Rohwerten mehr.

OAuth

Der OAuth-Ablauf für Clientanmeldedaten wird für die Server-zu-Server-Authentifizierung unterstützt:

Sie können diesen Ablauf verwenden, wenn der Generative AI App Builder der Ressourceneigentümer ist und Sie keine Endnutzerautorisierung benötigen.
Sie müssen die Client-ID, den Clientschlüssel und den Token-Endpunkt eines OAuth-Anbieters in Dialogflow CX konfigurieren.
Wir empfehlen, den Clientschlüssel mit Secret Manager bereitzustellen. Exportierte Agenten enthalten nach dem 15. August 2025 keine Clientschlüssel im Rohwertformat mehr.
Dialogflow CX tauscht ein OAuth-Zugriffstoken von einem OAuth-Anbieter aus und übergibt es im Autorisierungsheader der Anfrage.

Inhabertoken

Sie können die Bearer-Authentifizierung so konfigurieren, dass das Inhabertoken dynamisch vom Client übergeben wird. Dieses Token ist im Autorisierungsheader der Anfrage enthalten.
Beim Einrichten der Toolauthentifizierung können Sie einen Sitzungsparameter als Inhabertoken festlegen. Verwenden Sie beispielsweise $session.params.<parameter-name-for-token>, um das Token anzugeben.

Weisen Sie das Inhabertoken zur Laufzeit dem Sitzungsparameter zu:

DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}

Wenn Sie ein statisches Token konfigurieren müssen, anstatt das Token aus einem Sitzungsparameter abzurufen, empfehlen wir, das Token über Secret Manager bereitzustellen. Nach dem 15. August 2025 enthalten exportierte Agenten keine Inhabertoken mit Rohwerten mehr.

Gegenseitige TLS-Authentifizierung

Weitere Informationen finden Sie unter Gegenseitige TLS-Authentifizierung.
Benutzerdefinierte Clientzertifikate werden unterstützt. Sie können Clientzertifikate auf Agent-Ebene auf dem Tab Sicherheit in den Agent-Einstellungen einrichten.
Das Zertifikat (PEM-Format) und der private Schlüssel (PEM-Format) sind Pflichtfelder. Nachdem dieses Clientzertifikat festgelegt wurde, wird es während des gegenseitigen TLS für alle Tools und Webhooks verwendet.

Benutzerdefiniertes CA-Zertifikat

Weitere Informationen finden Sie unter Benutzerdefinierte CA-Zertifikate.

Secret Manager-Authentifizierung

Wenn Sie OAuth, einen API-Schlüssel oder ein Inhabertoken verwenden, können Sie die Anmeldedaten mit Secret Manager als Secrets speichern.

So authentifizieren Sie Ihr Tool mithilfe von Secrets:

Erstellen Sie ein Secret, falls Sie noch keines haben.
Weisen Sie dem Dialogflow-Dienst-Agenten die Rolle Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) für das neue Secret zu.
Kopieren Sie Ihre Anmeldedaten in die Zwischenablage.
Fügen Sie Ihrem Secret eine neue Secret-Version hinzu. Fügen Sie Ihre Anmeldedaten als Secret-Wert ein.
- Lassen Sie alle Zeilenumbruchzeichen am Ende des Secret-Werts weg.
Kopieren Sie den Namen der Secret-Version, die Sie gerade hinzugefügt haben. Das Namensformat ist projects/{project_id}/secrets/{secret_id}/versions/{version_id}.
Öffnen Sie den Bearbeitungsbildschirm des Tools und gehen Sie dann so vor:
- Wenn Sie OAuth verwenden, wählen Sie OAuth als Authentifizierungstyp aus. Klicken Sie dann unter Clientschlüssel auf Secret-Version und fügen Sie den Namen der Secret-Version in das Eingabefeld Secret-Version ein.
- Wenn Sie einen API-Schlüssel verwenden, wählen Sie API-Schlüssel als Authentifizierungstyp aus und klicken Sie dann unter API-Schlüssel auf Secret-Version. Fügen Sie den Namen der Secret-Version in das Eingabefeld Secret-Version ein.
- Wenn Sie ein Inhabertoken verwenden, wählen Sie Inhabertoken als Authentifizierungstyp aus und klicken Sie dann unter Inhabertoken auf Secret-Version. Fügen Sie den Namen der Secret-Version in das Eingabefeld Secret-Version ein.
Klicken Sie auf Speichern.

Privater Netzwerkzugriff für OpenAPI-Tool

Das OpenAPI-Tool lässt sich in den Zugriff auf private Netzwerke von Service Directory einbinden, um eine Verbindung zu API-Zielen in Ihrem VPC-Netzwerk herzustellen. Dadurch bleibt der Traffic im Google Cloud -Netzwerk und es werden IAM und VPC Service Controls erzwungen.

So richten Sie ein OpenAPI-Tool ein, das auf ein privates Netzwerk ausgerichtet ist:

Folgen Sie der Anleitung unter Private Netzwerkkonfiguration für Service Directory, um Ihr VPC-Netzwerk und Ihren Service Directory-Endpunkt zu konfigurieren.
Prüfen Sie, ob das Dienstkonto des Dialogflow CX-Dienst-Agents mit der folgenden Adresse für Ihr Agent-Projekt vorhanden ist:
```
service-agent-project-number@gcp-sa-dialogflow.
```
Weisen Sie dem Dienstkonto Dialogflow CX-Dienst-Agent die folgenden IAM-Rollen zu:
- servicedirectory.viewer des Service Directory-Projekts
- servicedirectory.pscAuthorizedService des Netzwerkprojekts
Geben Sie beim Erstellen des Tools den Service Directory-Dienst zusammen mit dem OpenAPI-Schema und optionalen Authentifizierungsinformationen an.

Zugriff auf Sitzungsparameter für OpenAPI-Tools

Die Eingaben für das OpenAPI-Tool werden aus der Unterhaltung des Nutzers mit dem LLM abgeleitet, wobei das Schema als Leitfaden dient. In einigen Situationen müssen Eingaben möglicherweise von Sitzungsparametern abgeleitet werden, die während eines Ablaufs erfasst oder als Suchparameter zusammen mit der Nutzereingabe bereitgestellt werden.

Sie können Sitzungsparameter, die Sie als Eingabe übergeben müssen, im folgenden Format angeben:

     parameters:
       - in: query
         name: petId
         required: true
         description: Pet id
         schema:
           type: integer
           x-agent-input-parameter: petId # Reads from the $session.params.petId
       - in: header
         name: X-other
         schema:
           type: string
           x-agent-input-parameter: $request.payload.header # Reads from the header specified in the request payload input
     requestBody:
       required: false
       content:
         application/json:
           schema:
             type: object
             properties:
               name:
                 type: string
                 x-agent-input-parameter: petName # Reads from the $session.params.petName
                 description: Name of the person to greet (optional).
               breed:
                 type: string
                 description: Breed of the pet.

Wenn keine solchen Sitzungsparameter verfügbar sind, wird die vom LLM generierte Eingabe an das Tool übergeben.

Standardwerte für OpenAPI-Tools

Sie können das OpenAPI-Schema verwenden, um Standardwerte anzugeben. Diese Standardwerte gelten nur, wenn für diesen Parameter oder diese Eigenschaft kein von einem LLM generierter Eingabewert oder ein auf Sitzungsparametern basierender Eingabewert verfügbar ist.

Sie können Standardwerte im Schema so angeben:

     parameters:
       - in: query
         name: zipcode
         required: true
         description: Zip code to search for
         schema:
           type: integer
           default: 94043
     requestBody:
       content:
         application/json:
           schema:
             type: object
             properties:
               breed:
                 type: string
                 description: Breed of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

Wenn kein LLM-generierter Wert, Sitzungsparameterwert oder Standardwert vorhanden ist, wird die Eingabe nicht angegeben.

Datenspeichertools

Weitere Informationen zur Verwendung von Datenspeicher-Tools mit einem Playbook finden Sie unter Datenspeicher-Tools.

Connector-Tools

Mit Connector-Tools können Sie einen KI-Agenten so konfigurieren, dass er Aktionen über die in Integration Connectors konfigurierten Verbindungen ausführt. Jedes Connector-Tool wird mit einer Verbindung und einer oder mehreren Aktionen konfiguriert. Sie können mehrere Tools für eine einzelne Verbindung erstellen, um verschiedene Aktionen zusammenzufassen, die Ihr KI-Agent verwenden soll.

Das Connector-Tool unterstützt die folgenden Connector-Typen:

Anhand von Beispielen können Sie Agenten zeigen, wie sie Connector-Tools effektiv einsetzen, indem Sie demonstrieren, wie die Tools aufgerufen und Antworten verwendet werden.

Verbindung herstellen

Wenn Sie eine Verbindung erstellen und mit Ihrem Agenten verbinden möchten, rufen Sie Tools > Erstellen auf, wählen Sie den Tooltyp Connector und den gewünschten Connectortyp aus und klicken Sie auf Verbindung erstellen. Dadurch wird die Erstellung von Integration Connectors mit mehreren vorausgefüllten Feldern geöffnet.

Alternativ können Sie zu Integration Connectors wechseln und der Anleitung zum Erstellen einer Verbindung folgen.

Connector-Aktionen

Sie können Ihrem Agenten für jedes Connector-Tool zwei Arten von Aktionen zur Verfügung stellen. Weitere Informationen finden Sie unter Entitäten, Vorgänge und Aktionen.

CRUD-Vorgänge für Entitäten:

Für jede Verbindung gibt es Entitäten entsprechend den Objekten dieser Datenquelle (für BigQuery sind dies Tabellen, für Salesforce Objekte wie Order oder Case).

Sie können für jede Entität CRUD-Vorgänge ausführen:
- Erstellen: Validiert und erstellt eine Entität mit den angegebenen Feldwerten.
- Auflisten: Filterbasierte Suche nach Entitätsinstanzen.
- Aktualisieren: Filterbasierte Methode zum Ändern von Entitätsfeldwerten.
- Löschen: Löscht eine Entität.
- Get: Ruft eine einzelne Entität anhand der entityId ab.
Hinweis: Der Get-Vorgang kann nur verwendet werden, um einen einzelnen Datensatz aus einer Entität mit einem Primärschlüssel abzurufen. Es ist oft praktischer, den List-Vorgang mit einer filterClause zu verwenden, um eine Entität abzurufen.

Weitere Informationen zu CRUD-Vorgängen für Entitäten finden Sie in der Dokumentation zu Connectors.
Connectorspezifische Aktionen:

Viele Connectors unterstützen die Aktion ExecuteCustomQuery, mit der Sie eine SQL-Abfrage für die Datenquelle ausführen können, wobei jede der Datenquellenentitäten als Tabelle referenziert werden kann. Weitere Informationen finden Sie in der Liste der unterstützten Connectors.

Die zusätzlichen Aktionen variieren je nach Connector-Typ. Beispiele finden Sie unter BigQuery-Connector-Aktionen oder Salesforce-Connector-Aktionen.

Eingabe-/Ausgabefelder für CRUD-Vorgänge konfigurieren

Wenn Sie bestimmte Eingabe- oder Ausgabefelder für die Aktion Ihres Connector-Tools auswählen, können Sie die Komplexität dieser Aktionen für den Agenten begrenzen.

Wenn Sie beispielsweise nur eine Entität mit einer Teilmenge ihrer Felder erstellen müssen, vereinfacht die Konfiguration dieser Felder in Ihrer Aktion die Aktion für den Agenten.

Wenn Sie eine Reihe von Ausgabefeldern angeben, wird die Größe der Toolantwort reduziert, um Tokenlimits zu umgehen. So kann der KI-Agent die Ausgabe verarbeiten, indem er nur die relevanten Felder bereitstellt.

Authentifizierung

Wenn die von Ihnen verwendete Verbindung das Überschreiben der Authentifizierung zulässt, konfigurieren Sie das Tool so, dass Anmeldedaten aus angegebenen Sitzungsparametern übergeben werden.

Geben Sie diese Anmeldedaten in den Sitzungsparametern ein. Das Tool übergibt sie dann automatisch an die Datenquelle, um sie beim Aufrufen von Aktionen zu authentifizieren.

Funktionstools

Wenn Sie Funktionen haben, auf die Ihr Clientcode zugreifen kann, OpenAPI-Tools aber nicht, können Sie Funktionstools verwenden. Funktionstools werden immer clientseitig ausgeführt, nicht vom Agenten.

So läuft der Vorgang ab:

Ihr Clientcode sendet eine Intent-Erkennungsanfrage.
Der KI-Agent erkennt, dass ein Funktionstool erforderlich ist, und die Antwort zur Intent-Erkennung enthält den Namen des Tools sowie Eingabeargumente. Diese Sitzung wird pausiert, bis eine weitere Intent-Erkennungsanfrage mit dem Tool-Ergebnis eingeht.
Ihr Clientcode ruft das Tool auf.
Ihr Clientcode sendet eine weitere Intent-Erkennungsanfrage, die das Tool-Ergebnis als Ausgabeargumente bereitstellt.

Das folgende Beispiel zeigt das Eingabe- und Ausgabeschema eines Funktionstools:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, for example, San Francisco, CA"
    }
  },
  "required": [
    "location"
  ]
}

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "The temperature"
    }
  }
}

Das folgende Beispiel zeigt die erste Intent-Erkennungsanfrage und die Antwort mit REST:

HTTP method and URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
{
  "queryInput": {
    "text": {
      "text": "what is the weather in Mountain View"
    },
    "languageCode": "en"
  }
}

{
  "queryResult": {
    "text": "what is the weather in Mountain View",
    "languageCode": "en",
    "responseMessages": [
      {
        "source": "VIRTUAL_AGENT",
        "toolCall": {
          "tool": "<tool-resource-name>",
          "action": "get-weather-tool",
          "inputParameters": {
            "location": "Mountain View"
          }
        }
      }
    ]
  }
}

Das folgende Beispiel zeigt die zweite Intent-Erkennungsanfrage, die das Tool-Ergebnis liefert:

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

Clientseitige Ausführung

Sie können OpenAPI- und Datenspeichertools auf der Clientseite ausführen, ähnlich wie Funktionstools, indem Sie bei der Interaktion mit der Sitzung einen API-Überschreibungswert anwenden.