Einige Produkte und Funktionen werden derzeit umbenannt. Auch die Funktionen für generative Playbooks und Abläufe werden zu einer einzigen konsolidierten Console migriert. Weitere Informationen

Diese Seite wurde von der Cloud Translation API übersetzt.

Playbook-Tools
Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Mithilfe von Tools können Sie Playbooks mit externen Systemen verbinden. Diese Systeme können das Wissen der Playbooks ergänzen und sie dabei unterstützen, komplexe Aufgaben effizient auszuführen.

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

Tool-Tests

Nachdem Sie ein Tool erstellt haben, können Sie mit der Funktion zum Testen von Tools prüfen, ob es funktioniert. Klicken Sie in der Ansicht eines Tools auf die Schaltfläche Testen über dem Toolbereich. Dadurch wird das Tool für die Eingabe im Simulator geöffnet. Geben Sie die Tool-Eingabe ein und klicken Sie dann auf Ausgabe ansehen, um die korrekte Tool-Ausgabe zu überprü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 Kundenservicemitarbeitern aktivieren, ohne sie manuell konfigurieren zu müssen.

Folgende integrierte Tools werden unterstützt:

Code Interpreter: Ein Tool von Google, das die Funktionen zur Codegenerierung und -ausführung kombiniert und es Nutzern ermöglicht, verschiedene Aufgaben auszuführen, z. B. Datenanalyse, Datenvisualisierung, Textverarbeitung, Lösen von Gleichungen oder Optimierungsproblemen.

Ihr Bot ist optimiert, um zu bestimmen, wie und wann diese Tools aufgerufen werden sollen. Sie können jedoch zusätzliche Beispiele für Ihre Anwendungsfälle angeben.

Beispiele sollten ein Schema wie das folgende haben:

{
  "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 Kundenservicemitarbeiter kann mithilfe eines OpenAPI-Tools eine Verbindung zu einer externen API herstellen, indem er das OpenAPI-Schema angibt. Standardmäßig ruft der Kundenservicemitarbeiter die API in Ihrem Namen auf. Alternativ können Sie OpenAPI-Tools clientseitig 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

Optional können Sie die interne Schemareferenz @dialogflow/sessionId als Parameterschematyp verwenden. Bei diesem Parameterschematyp wird die Dialogflow-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 des OpenAPI-Tools

Es gelten folgende Einschränkungen:

Unterstützte Parametertypen sind path, query und header. Der Parametertyp cookie wird noch nicht unterstützt.
Von OpenAPI-Schemas definierte Parameter unterstützen die folgenden Datentypen: string, number, integer, boolean und array. Der Typ object wird noch nicht unterstützt.
Derzeit können Sie im Beispieleditor der Console keine Abfrageparameter angeben.
Der Anfrage- und Antworttext muss leer oder JSON sein.

API-Authentifizierung im OpenAPI-Tool

Beim Aufrufen einer externen API werden die folgenden Authentifizierungsoptionen unterstützt:

Dialogflow-Dienst-Agent-Authentifizierung
- Dialogflow kann mit dem Dialogflow-Dienst-Agenten ein ID-Token oder ein Zugriffstoken generieren. Das Token wird dem Autorisierungs-HTTP-Header hinzugefügt, wenn Dialogflow eine externe API aufruft.
- Ein ID-Token kann zum Zugriff auf Cloud Run-Funktionen und Cloud Run-Dienste verwendet werden, nachdem Sie service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com die Rollen roles/cloudfunctions.invoker und roles/run.invoker zugewiesen haben. Wenn sich die Cloud Run-Funktionen und Cloud Run-Dienste im selben Ressourcenprojekt befinden, benötigen Sie keine zusätzlichen IAM-Berechtigungen, um sie aufzurufen.
- Ein Zugriffstoken kann zum Zugriff auf andere Google Cloud APIs verwendet werden, nachdem Sie service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com die erforderlichen Rollen gewährt haben.
Authentifizierung über Dienstkonto
- Dienstkonten können verwendet werden, um Toolanfragen an alle Google APIs zu authentifizieren, die dies unterstützen. Da es sich bei Dienstkonten um Hauptkonten handelt, können Sie ihnen Zugriff auf Ressourcen in Ihrem Projekt gewähren, indem Sie ihnen eine Rolle zuweisen, wie Sie es auch für jedes andere Hauptkonto tun würden. Anhand der E-Mail-Adresse des Dienstkontos wird ein Zugriffstoken generiert, das im Authorization-Header der Toolanfrage gesendet wird.
- Für die Nutzung dieser Funktion sind die folgenden Berechtigungen erforderlich:
  - roles/iam.serviceAccountUser-Rolle für den Nutzer, der das Tool erstellt oder aktualisiert, um die Dienstkontoauthentifizierung zu verwenden.
  - roles/iam.serviceAccountTokenCreator-Rolle dem Dialogflow-Dienst-Agent zu.
- Wenn Sie Dienstkonten in mehreren Projekten verwenden möchten, muss dies in Ihrer Organisationsrichtlinie unterstützt werden. Beide Berechtigungen müssen im Projekt gewährt werden, das das Dienstkonto enthält.
API-Schlüssel
- Sie können die API-Schlüsselauthentifizierung konfigurieren, indem Sie den Schlüsselnamen, den Anfragespeicherort (Header oder Suchstring) und den API-Schlüssel angeben, damit Dialogflow den API-Schlüssel in der Anfrage übergibt.
- Wir empfehlen, den API-Schlüssel über Secret Manager anzugeben.
OAuth
- Der OAuth-Vorgang für Clientanmeldedaten wird für die Server-zu-Server-Authentifizierung unterstützt:
  - Dieser Ablauf kann verwendet werden, wenn die Agent Builder Console der Ressourceninhaber ist und keine Autorisierung durch den Endnutzer erforderlich ist.
  - Client-ID, Clientschlüssel und Token-Endpunkt des OAuth-Anbieters müssen in Dialogflow konfiguriert werden.
    - Wir empfehlen, das Client-Secret über Secret Manager anzugeben.
  - Dialogflow tauscht ein OAuth-Zugriffstoken vom OAuth-Anbieter aus und gibt es im Authentifizierungsheader der Anfrage weiter.
- Für andere OAuth-Abläufe, die eine Autorisierung durch den Endnutzer erfordern, z. B. den Autorisierungscode-Ablauf und den PKCE-Ablauf:
  1. Sie müssen Ihre eigene Anmelde-UI implementieren und das Zugriffstoken auf der Clientseite abrufen.
  2. Du hast dann die Wahl zwischen zwei Optionen:
    
    a. Verwenden Sie die Option „Inhabertoken-Authentifizierung“, um das Token an das OpenAPI-Tool weiterzuleiten. Dialogflow fügt dieses Token beim Aufrufen des Tools in den Autorisierungsheader ein.
    
    b. Mit dem Funktionstool können Sie das Tool selbst auf Clientseite aufrufen und das Ergebnis des Toolaufrufs an Dialogflow übergeben.
Inhabertoken
- Sie können die Bearer-Authentifizierung so konfigurieren, dass das Bearer-Token dynamisch vom Client übergeben wird. Dieses Token ist im Auth-Header der Anfrage enthalten.
- Wenn Sie die Tool-Authentifizierung einrichten, können Sie einen Sitzungsparameter als Bearer-Token festlegen. Verwenden Sie beispielsweise $session.params.<parameter-name-for-token>, um das Token anzugeben.
- Weisen Sie dem Sitzungsparameter zur Laufzeit das Bearer-Token zu:
```
DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}
```
- Wenn du ein statisches Token konfigurieren musst, anstatt das Token aus einem Sitzungsparameter abzurufen, empfehlen wir dir, dein Token über Secret Manager bereitzustellen.
Gegenseitige TLS-Authentifizierung
- Weitere Informationen finden Sie in der Dokumentation zur gegenseitigen TLS-Authentifizierung.
- Benutzerdefinierte Clientzertifikate werden unterstützt. Sie können Clientzertifikate auf Kundenservicemitarbeiterebene in den Einstellungen für Kundenservicemitarbeiter auf dem Tab „Sicherheit“ einrichten. Das Zertifikat (PEM-Format) und der private Schlüssel (PEM-Format) sind Pflichtfelder. Nach der Einrichtung wird dieses Clientzertifikat bei der gegenseitigen TLS-Authentifizierung für alle Tools und Webhooks verwendet.
Benutzerdefiniertes CA-Zertifikat
- Weitere Informationen finden Sie in der Dokumentation zu benutzerdefinierten CA-Zertifikaten.

Secret Manager-Authentifizierung

Wenn Sie OAuth, einen API-Schlüssel oder ein Bearer-Token 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-Agent die Rolle Zugriffsperson für Secret Manager-Secret (roles/secretmanager.secretAccessor) für das neue Secret zu.
Kopieren Sie die Anmeldedaten in die Zwischenablage.
Fügen Sie Ihrem Secret eine neue Secret-Version hinzu. Fügen Sie Ihre Anmeldedaten als geheimen Wert ein.
- Fügen Sie am Ende kein Zeilenumbruchzeichen ein.
Kopieren Sie den Namen der soeben hinzugefügten Secret-Version. Das Format des Namens ist projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
Öffnen Sie den Bearbeitungsbildschirm des Tools und gehen Sie 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 Bearer-Token verwenden, wählen Sie Bearer-Token als Authentifizierungstyp aus und klicken Sie dann unter Bearer-Token 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 das OpenAPI-Tool

Das OpenAPI-Tool wird in privaten Service Directory-Zugriff eingebunden, sodass eine Verbindung zu API-Zielen in Ihrem VPC-Netzwerk hergestellt werden kann. Dadurch wird der Traffic innerhalb des Google Cloud-Netzwerks beibehalten und IAM sowie 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.
Das Dienstkonto Dialogflow-Dienst-Agent mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Weisen Sie dem Dienstkonto Dialogflow-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 mit dem OpenAPI-Schema und optionalen Authentifizierungsinformationen an.

Zugriff auf Sitzungsparameter des OpenAPI-Tools

Die Eingaben des Open API-Tools werden aus der Unterhaltung des Nutzers mit dem LLM abgeleitet, wobei das Schema als Leitfaden dient. In einigen Fällen müssen Eingaben aus Sitzungsparametern abgeleitet werden, die während eines Ablaufs erfasst wurden, oder zusammen mit der Nutzereingabe als Abfrageparameter eingegeben werden.

Der Sitzungsparameter, der als Eingabe übergeben werden muss, kann so angegeben werden:

     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: Bread of the pet.

Wenn kein solcher Sitzungsparameter verfügbar ist, wird die von LLM generierte Eingabe an das Tool übergeben.

Standardwerte des OpenAPI-Tools

Mit dem Open API-Schema können Sie Standardwerte angeben. Die Standardwerte werden nur verwendet, wenn für diesen Parameter oder diese Property kein von LLM generierter Eingabewert oder ein auf Sitzungsparametern basierender Eingabewert vorhanden ist.

Die Standardwerte können als Teil des Schemas so angegeben werden:

     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: Bread of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

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

Datenspeichertools

Informationen zur Verwendung von Datenspeichertools mit einem Playbook finden Sie in der Dokumentation zu Datenspeichertools.

Connector-Tools

Mit Connector-Tools können Kundenservicemitarbeiter Aktionen mithilfe der in Integration Connectors konfigurierten Verbindungen ausführen. Jedes Connector-Tool ist mit einer einzelnen Verbindung und einer oder mehreren Aktionen konfiguriert. Bei Bedarf können für eine einzelne Verbindung mehrere Tools erstellt werden, um verschiedene Aktionen für Kundenservicemitarbeiter zu gruppieren.

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

Beispiele sollten verwendet werden, um die Nutzung von Connector-Tools durch Kundenservicemitarbeiter zu verbessern, indem gezeigt wird, wie der Kundenservicemitarbeiter das Tool aufrufen und die Antwort verwenden sollte.

Verbindung herstellen

Wenn Sie eine Verbindung erstellen und mit Ihrem Kundenservicemitarbeiter verknüpfen möchten, klicken Sie auf Tools > Erstellen, wählen Sie den Tooltyp Connector und den gewünschten Connectortyp aus und klicken Sie auf die Schaltfläche Verbindung erstellen. Daraufhin gelangen Sie zum Erstellen von Integration Connectors, wobei einige Felder bereits ausgefüllt sind.

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

Connector-Aktionen

Für jedes Connector-Tool gibt es zwei Arten von Aktionen, die für deinen Kundenservicemitarbeiter verfügbar gemacht werden können. Weitere Informationen findest du unter Entitäten, Vorgänge und Aktionen.

CRUD-Vorgänge für Entitäten

Jede Verbindung hat „Entitäten“, die den Objekten dieser Datenquelle entsprechen. Bei BigQuery sind das Tabellen, bei Salesforce Objekte wie „Order“ oder „Case“.

Sie können CRUD-Vorgänge für jede Entität ausführen:
- Erstellen: Erstellt eine Entität mit den angegebenen Feldwerten.
- List: filterbasierte Suche nach Entitätsinstanzen
- Aktualisieren: Filterbasierte Methode zum Ändern von Entitätsfeldwerten
- Löschen: Entität wird gelöscht.
- Mit Get wird eine einzelne Entität anhand der Entitäts-ID abgerufen.
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 Connectors-Dokumentation.
Connectorspezifische Aktionen

Viele Connector unterstützen die Aktion ExecuteCustomQuery, mit der eine SQL-Abfrage an der Datenquelle ausgeführt werden kann. Dabei können alle Entitäten der Datenquelle als Tabellen referenziert werden. In dieser Liste finden Sie eine Liste der unterstützten Connectors.

Zusätzliche Aktionen unterscheiden sich je nach Connectortyp. Weitere Informationen 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 des Connector-Tools auswählen, können Sie die Komplexität dieser Aktionen für den Kundenservicemitarbeiter einschränken.

Wenn Sie beispielsweise nur ein Entitätsobjekt mit einer Teilmenge der zugehörigen Felder erstellen müssen, vereinfacht die Konfiguration dieser Felder in Ihrer Aktion die Aktion für den Kundenservicemitarbeiter.

Wenn Sie eine Reihe von Ausgabefeldern angeben, wird die Größe der Tool-Antwort reduziert. Das ist hilfreich, wenn Tokenlimits ein Problem darstellen. Außerdem werden nur die relevanten Felder angezeigt, was die Verarbeitung der Ausgabe durch den Kundenservicemitarbeiter vereinfacht.

Authentifizierung

Wenn die verwendete Verbindung für die Überschreibung der Authentifizierung konfiguriert ist, kann das Tool so konfiguriert werden, dass Anmeldedaten aus den angegebenen Sitzungsparametern übergeben werden.

Sie als Entwickler des Kundenservicemitarbeiters sind dafür verantwortlich, wie diese Anmeldedaten in die Sitzungsparameter eingefügt werden. Das Tool gibt sie automatisch an die Datenquelle weiter, die für die Authentifizierung verwendet werden soll, wenn die Aktionen des Tools aufgerufen werden.

Funktionstools

Wenn Funktionen über Ihren Clientcode, aber nicht über OpenAPI-Tools zugänglich sind, können Sie Funktionstools verwenden. Funktionstools werden immer clientseitig ausgeführt, nicht vom Kundenservicemitarbeiter.

So läuft der Vorgang ab:

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

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 Anfrage und Antwort für die Erkennung von Intents 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 Anfrage zum Erkennen von Absichten, die das Tool-Ergebnis liefert:

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

Clientseitige Ausführung

Ähnlich wie Funktionstools können OpenAPI- und Datenspeichertools auf der Clientseite ausgeführt werden, indem bei der Interaktion mit der Sitzung eine API-Überschreibung angewendet wird.

Beispiel:

DetectIntentRequest {
  ...
  query_params {
    playbook_state_override {
      playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
    }
  }
  ...
}