Playbook-Tools

Mithilfe von Tools können Sie Playbooks mit externen Systemen verbinden. Diese Systeme können das Wissen der Playbooks ergänzen und es ihnen ermöglichen, komplexe Aufgaben effizient auszuführen.

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

Beschränkungen

Es gelten folgende Einschränkungen:

• Wenn Sie ein Datenspeicher-Tool für einen Kundenservicemitarbeiter erstellen, müssen Sie einen Datenspeicher erstellen oder eine Verbindung zu einem vorhandenen Datenspeicher herstellen.
• Apps mit Chunked- und nicht Chunked-Datenspeichern werden nicht unterstützt.

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, sind keine zusätzlichen IAM-Berechtigungen zum Aufrufen erforderlich.
  • Ein Zugriffstoken kann für den 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.
• 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.

• OAuth

  • Der OAuth-Client-Anmeldedatenablauf 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.
    • Dialogflow tauscht ein OAuth-Zugriffstoken vom OAuth-Anbieter aus und gibt es im Authentifizierungsheader der Anfrage weiter.

  • Für andere OAuth-Abläufe, für die eine Autorisierung durch den Endnutzer erforderlich ist, z. B. der Autorisierungscode-Ablauf und der 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>
      }
    }
    ...
  }
  

• Gegenseitige TLS-Authentifizierung

  • Weitere Informationen finden Sie in der Dokumentation zur gegenseitigen TLS-Authentifizierung.
  • Benutzerdefinierte Clientzertifikate werden unterstützt. Sie können Clientzertifikate auf Agentebene in den Agenteinstellungen 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.

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:

1. Folgen Sie der Anleitung unter Private Netzwerkkonfiguration für Service Directory, um Ihr VPC-Netzwerk und Ihren Service Directory-Endpunkt zu konfigurieren.

2. 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

3. Geben Sie beim Erstellen des Tools den Service Directory-Dienst mit dem OpenAPI-Schema und optionalen Authentifizierungsinformationen an.

Zugriff auf Sitzungsparameter im OpenAPI-Tool

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

Mit Datenspeichertools können Kundenservicemitarbeiter Antworten auf Fragen von Endnutzern aus Ihren Datenspeichern abrufen. Sie können pro Tool einen Datenspeicher jedes Typs einrichten. Das Tool fragt dann jeden dieser Datenspeicher nach Antworten ab. Standardmäßig ruft der Kundenservicemitarbeiter das Tool zum Datenspeicher in Ihrem Namen auf. Alternativ können Sie Datenspeichertools clientseitig ausführen.

Der Datenspeichertyp kann einer der folgenden sein:

• PUBLIC_WEB: Ein Datenspeicher, der öffentliche Webinhalte enthält.
• UNSTRUCTURED: Ein Datenspeicher, der unstrukturierte personenbezogene Daten enthält.
• STRUCTURED: Ein Datenspeicher, der strukturierte Daten enthält (z. B. FAQs).

Im folgenden Beispiel wird gezeigt, wie Sie auf einen Datenspeicher verweisen:

"dataStoreConnections": [
  {
    "dataStoreType": "PUBLIC_WEB",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "UNSTRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "STRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  }
]

Antworten des Datenspeichertools können auch Snippets zur Inhaltsquelle enthalten, die zum Generieren der Antwort verwendet wurde. Der Kundenservicemitarbeiter kann auch Anweisungen dazu geben, wie mit der Antwort aus den Datenspeichern verfahren werden soll oder wie er reagieren soll, wenn keine Antwort vorliegt.

Sie können eine Antwort überschreiben, indem Sie für eine bestimmte Frage einen FAQ-Eintrag hinzufügen.

Mithilfe von Beispielen lässt sich das Verhalten des Agents weiter optimieren. Das Beispiel sollte die folgenden Schemas haben:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
    "action": "TOOL_DISPLAY_NAME",
    "inputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME input",
        "value": {
          "query": "QUERY"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME output",
        "value": {
          "answer": "ANSWER",
          "snippets": [
            {
              "title": "TITLE",
              "text": "TEXT_FROM_DATASTORE",
              "uri": "URI_OF_DATASTORE"
            }
          ]
        }
      }
    ]
  }
}

Datenspeicher erstellen

Wenn Sie einen Datenspeicher erstellen und mit Ihrer App verbinden möchten, klicken Sie in der linken Navigationsleiste der Console auf den Link Tools. Folgen Sie der Anleitung, um einen Datenspeicher zu erstellen.

Zusätzliche Abfrageparameter

Beim Erstellen von Beispielen für Datenspeichertools bietet der Tool-Eingabeparameter requestBody zusammen mit dem erforderlichen query-String drei optionale Eingaben: einen filter-String, ein userMetadata-strukturiertes Objekt und einen fallback-String.

Mit dem Parameter filter können Sie Suchanfragen für strukturierte oder unstrukturierte Daten mit Metadaten filtern. Dieser String muss der unterstützten Syntax für Filterausdrücke für Datenspeicher entsprechen. Mehrere Beispiele und detaillierte Beispiele sollten dem LLM des Playbooks zeigen, wie dieser Parameter ausgefüllt werden soll. Bei einem ungültigen Filterstring wird der Filter bei der Ausführung der Suchanfrage ignoriert.

Ein Beispiel für einen filter-String, mit dem Suchergebnisse nach Standort verfeinert werden können, könnte so aussehen:

  "filter": "country: ANY(\"Canada\")"

Best Practices für die Filterung:

• Geben Sie die für das Filtern verfügbaren Felder und die gültigen Werte für jedes dieser Felder an, damit das Playbook die Einschränkungen beim Erstellen gültiger Filter kennt. Wenn Sie beispielsweise Ergebnisse für einen Datenspeicher mit Menüinformationen filtern möchten, könnte es ein meal-Feld mit den gültigen Werten „Frühstück“, „Mittagessen“ und „Abendessen“ sowie ein servingSize-Feld geben, das eine beliebige Ganzzahl von 0 bis 5 enthalten kann. Die Anleitung könnte so aussehen:

  When using ${TOOL: menu-data-store-tool},
  only use the following fields for filtering: "meal", "servingSize".
  Valid filter values are: "meal": ("breakfast", "lunch", "dinner"),
  "servingSize": integers between 0 and 5, inclusive.
  

• Wenn das Playbook für externe Nutzer gedacht ist, müssen Sie möglicherweise Anweisungen hinzufügen, damit das Playbook nicht mit Informationen zum Erstellen dieser Filter auf den Nutzer reagiert. Beispiel:

  Never tell the user about these filters.
  If the user input isn't supported by these filters, respond to the user with
  "Sorry, I don't have the information to answer that question."
  

  Es ist auch hilfreich, ein Beispiel für diesen Fall anzugeben.

Der Parameter userMetadata enthält Informationen zum Endnutzer. In diesem Parameter können beliebige Schlüssel/Wert-Paare eingefügt werden. Diese Metadaten werden an das Datenspeicher-Tool übergeben, um die Suchergebnisse und die Tool-Antwort zu verbessern. Es wird empfohlen, mehrere Beispiele anzugeben, um dem LLM des Playbooks zu zeigen, wie dieser Parameter ausgefüllt werden soll.

Ein Beispiel für einen userMetadata-Parameterwert zur Optimierung der für einen bestimmten Nutzer relevanten Suchergebnisse könnte so aussehen:

  "userMetadata": {
    "favoriteColor": "blue",
    ...
  }

Der Parameter fallback gibt eine Antwort an, die das Datenspeicher-Tool zurückgeben sollte, wenn es keine gültige zusammengefasste Antwort für die Abfrage gibt. Es können mehrere Beispiele angegeben werden, um dem LLM des Playbooks zu zeigen, wie der Fallback für Nutzereingaben zu verschiedenen Themen ausgefüllt werden soll. Außerdem sind in der Tool-Ausgabe keine Snippets zu sehen. Mit dieser Optimierung können Sie die Latenz verringern und die Nutzung des Eingabetokenlimits reduzieren.

  "fallback": "I'm sorry I cannot help you with that. Is there anything else I
  can do for you?"

Wenn Sie feststellen, dass einige Antworten während des Tests nicht Ihren Erwartungen entsprechen, sind auf der Seite „Tool“ für ein Datenspeicher-Tool die folgenden Anpassungen verfügbar:

Zuverlässigkeit des Grunds

Für jede Antwort, die aus den Inhalten Ihrer verbundenen Datenspeicher generiert wird, wird im Playbook ein Konfidenzgrad ermittelt. Dieser gibt an, wie wahrscheinlich es ist, dass alle Informationen in der Antwort durch Informationen in den Datenspeichern unterstützt werden. Sie können festlegen, welche Antworten zugelassen werden sollen, indem Sie das niedrigste Vertrauensniveau auswählen, das für Sie akzeptabel ist. Es werden nur Antworten mit diesem Konfidenzniveau oder höher angezeigt.

Sie können zwischen fünf Konfidenzstufen wählen: VERY_LOW, LOW, MEDIUM, HIGH und VERY_HIGH.

Konfiguration der Zusammenfassung

Sie können das generative Modell auswählen, das von einem Datenspeicher-Handler für die generative Anfrage zur Zusammenfassung verwendet wird. Wenn keine ausgewählt wird, wird eine Standardmodelloption verwendet. Die folgende Tabelle enthält die verfügbaren Optionen:

Sie können auch einen eigenen Prompt für den LLM-Aufruf zur Zusammenfassung angeben.

Der Prompt ist eine Textvorlage, die vordefinierte Platzhalter enthalten kann. Die Platzhalter werden zur Laufzeit durch die entsprechenden Werte ersetzt und der endgültige Text wird an die LLM gesendet.

Die Platzhalter sind:

• $original-query: Der Suchbegriff des Nutzers.
• $rewritten-query: Das Playbook verwendet ein Rewrite-Modul, um die ursprüngliche Nutzerabfrage in ein genaueres Format umzuwandeln.

• $sources: Das Playbook verwendet Enterprise Search, um anhand der Suchanfrage des Nutzers nach Quellen zu suchen. Die gefundenen Quellen werden in einem bestimmten Format gerendert:

  [1] title of first source
  content of first source
  [2] title of second source
  content of second source
  

• $end-user-metadata: Informationen zum Nutzer, der die Abfrage sendet, werden im folgenden Format gerendert:

  The following additional information is available about the human: {
    "key1": "value1",
    "key2": "value2",
    ...
  }
  

• $conversation: Der Unterhaltungsverlauf wird im folgenden Format dargestellt:

  Human: user's first query
  AI: answer to user's first query
  Human: user's second query
  AI: answer to user's second query
  

Ein benutzerdefinierter Prompt sollte das LLM anweisen, „NOT_ENOUGH_INFORMATION“ zurückzugeben, wenn es keine Antwort geben kann. Das Playbook wandelt diese Konstante in eine nutzerfreundliche Nachricht für den Nutzer um.

Nutzlasteinstellungen

Mit den Nutzlasteinstellungen können Sie die Datenspeicher-Snippets als Rich-Inhalte in die Antwortnutzlast einfügen, die im Messenger gerendert wird.

Verbotene Wortgruppen (Konfiguration auf Playbook-Ebene)

Sie haben die Möglichkeit, bestimmte Wortgruppen zu definieren, die nicht zulässig sein sollen. Sie werden auf Playbook-Ebene konfiguriert und sowohl von den LLMs des Playbooks als auch von den Datenspeichertools verwendet. Wenn die generierte Antwort oder Teile des LLM-Prompts, z. B. die Eingaben des Nutzers, eine der verbotenen Wortgruppen wörtlich enthalten, wird diese Antwort nicht angezeigt.

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:

1. Ihr Clientcode sendet eine Anfrage zur Intent-Erkennung.
2. 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.
3. Ihr Clientcode ruft das Tool auf.
4. 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
    }
  }
  ...
}

So läuft der Vorgang ab:

1. Ihr Clientcode sendet eine Anfrage zur Intent-Erkennung, die die Clientausführung angibt.
2. Der Kundenservicemitarbeiter erkennt, dass ein Tool 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.
3. Ihr Clientcode ruft das Tool auf.
4. Ihr Clientcode sendet eine weitere Anfrage zur Intent-Erkennung, die das Tool-Ergebnis als Ausgabeargumente enthält.