Diese Seite wurde von der Cloud Translation API übersetzt.

Tools

Mithilfe von Tools können Sie Agent-Apps mit externen Systemen verbinden. Diese Systeme können das Wissen über Kundenservicemitarbeiter-Apps erweitern und sie unterstützen. um komplexe Aufgaben effizient auszuführen.

Sie können integrierte Tools verwenden. oder maßgeschneiderte Tools erstellen.

Beschränkungen

Es gelten folgende Einschränkungen:

Sie müssen einen Datenspeicher erstellen (oder einen vorhandenen Datenspeicher verbinden). wenn ein Datenspeichertool für eine Agent-Anwendung erstellt wird.
Apps mit beidem in aufgeteilte und nicht aufgeteilte Datenspeicher werden nicht unterstützt.

Integrierte Tools

Integrierte Tools werden von Google gehostet. Du kannst diese Tools in Agent-Apps aktivieren ohne manuelle Konfiguration.

Folgende integrierte Tools werden unterstützt:

Code Interpreter: Ein von Google selbst entwickeltes Tool, das Codegenerierung und -ausführung kombiniert und dem Nutzer verschiedene Aufgaben wie Datenanalyse, Datenvisualisierung, Textverarbeitung, das Lösen von Gleichungen oder Optimierungsprobleme ermöglicht.

Ihre Agent-App ist so optimiert, dass festgelegt wird, wie und wann diese Tools aufgerufen werden sollen. Sie können aber auch zusätzliche Beispiele für Ihre Anwendungsfälle bereitstellen.

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

Eine Agent-Anwendung kann mithilfe eines OpenAPI-Tools eine Verbindung zu einer externen API herstellen indem Sie das OpenAPI-Schema bereitstellen. Standardmäßig ruft die Agent-App die API in Ihrem Namen auf. Alternativ können Sie die 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 verwenden. als Parameterschematyp festlegen. Bei diesem Parameterschematyp Die Dialogflow-Sitzungs-ID für die aktuelle Unterhaltung als Parameterwert bereitgestellt. Beispiel:

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

Einschränkungen für das OpenAPI-Tool

Es gelten folgende Einschränkungen:

Unterstützte Parametertypen sind path, query und header. Der Parametertyp cookie wird noch nicht unterstützt.
Durch das OpenAPI-Schema definierte Parameter unterstützen die folgenden Datentypen: string, number, integer, boolean, 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 im JSON-Format sein.

API-Authentifizierung des OpenAPI-Tools

Die folgenden Authentifizierungsoptionen werden beim Aufruf von einer externen API:

Dialogflow-Dienst-Agent-Authentifizierung <ph type="x-smartling-placeholder">
- Dialogflow kann ein ID-Token generieren. oder Zugriffstoken mithilfe von Dialogflow-Dienst-Agent. Das Token wird dem Autorisierungs-HTTP-Header hinzugefügt, wenn Dialogflow eine externe API aufruft.
- Mit einem ID-Token kann auf Cloud Functions- und Cloud Run-Dienste zugegriffen werden nachdem Sie die Rollen roles/cloudfunctions.invoker und roles/run.invoker service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Wenn sich die Cloud Functions- und Cloud Run-Dienste im selben Ressourcenprojekt befinden, benötigen Sie keine zusätzliche IAM-Berechtigung, um sie aufzurufen.
- Ein Zugriffstoken kann verwendet werden, um auf andere Google Cloud APIs zuzugreifen, nachdem Sie erforderliche Rollen, um service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
API-Schlüssel <ph type="x-smartling-placeholder">
- Sie können die API-Schlüsselauthentifizierung konfigurieren, indem Sie den Schlüsselnamen, Standort der Anfrage (Header oder Abfragestring) und den API-Schlüssel, damit Dialogflow den API-Schlüssel in der Anfrage übergibt.
OAuth <ph type="x-smartling-placeholder">
- Der OAuth-Vorgang für die Anmeldedaten des OAuth-Clients wird für die Server-zu-Server-Authentifizierung unterstützt. Client-ID, Clientschlüssel und Tokenendpunkt vom OAuth-Anbieter erforderlich die in Dialogflow konfiguriert werden soll. Dialogflow tauscht ein OAuth-Zugriffstoken aus und übergibt sie im auth-Header der Anfrage.
- Bei anderen OAuth-Abläufen müssen Sie das Funktionstool verwenden, mit Ihrer eigenen Anmelde-UI, um das Token auszutauschen.
Inhabertoken
- Sie können die Inhaberauthentifizierung so konfigurieren, dass das Inhabertoken dynamisch weitergegeben wird. von der Kundschaft. Dieses Token ist im auth-Header der Anfrage enthalten.
- Beim Einrichten der Tool-Authentifizierung können Sie einen Sitzungsparameter festlegen um als Inhaber-Token zu fungieren. Verwenden Sie beispielsweise $session.params.<parameter-name-for-token>, um das Token anzugeben.
- Weisen Sie zur Laufzeit dem Sitzungsparameter das Inhabertoken zu:
```
DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}
```
Gegenseitige TLS-Authentifizierung
- Weitere Informationen finden Sie im Hilfeartikel Gegenseitige TLS-Authentifizierung. Dokumentation.
Benutzerdefiniertes CA-Zertifikat
- Weitere Informationen finden Sie in der Dokumentation zu benutzerdefinierten CA-Zertifikaten.

Privater Netzwerkzugriff mit OpenAPI-Tool

Das OpenAPI-Tool lässt sich Zugriff auf private Netzwerke auf Service Directory damit 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 für ein privates Netzwerk ein:

Folgen Sie der Anleitung unter Private Netzwerkkonfiguration für Service Directory, um Ihr VPC-Netzwerk und Ihren Service Directory-Endpunkt zu konfigurieren.
Dialogflow-Dienst-Agent Dienstkonto mit der folgenden Adresse für Ihr Agent-Projekt vorhanden sein:
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Gewähren Sie dem Dienstkonto Dialogflow-Dienst-Agent die folgenden IAM-Rollen:
- servicedirectory.viewer des Service Directory-Projekts
- servicedirectory.pscAuthorizedService des Netzwerkprojekts
Service Directory Service zusammen mit dem OpenAPI-Schema bereitstellen und optionale Authentifizierungsinformationen beim Erstellen des Tools.

Datenspeichertools

Datenspeichertools können von einer Agent-Anwendung verwendet werden nach Antworten auf Endnutzerfragen aus Ihrem Datenspeichern. Sie können einen Datenspeicher jedes Typs pro Tool einrichten, und das Tool fragt in jedem dieser Datenspeicher nach Antworten ab. Standardmäßig ruft die Agent-App das Datenspeichertool 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 private Daten enthält.
STRUCTURED: Ein Datenspeicher, der strukturierte Daten enthält (z. B. FAQ).

Das folgende Beispiel zeigt, 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"
  }
]

Die Antworten des Datenspeichertools können auch Snippets zur Contentquelle enthalten. mit dem die Antwort generiert wurde. Die App des Kundenservicemitarbeiters kann weitere Anweisungen zum weiteren Vorgehen enthalten mit der Antwort aus den Datenspeichern oder wie du reagierst, wenn es keine Antwort gibt.

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

Beispiele können verwendet werden, um das Verhalten der Agent-App weiter zu verbessern. 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

Um einen Datenspeicher zu erstellen und mit Ihrer App zu verbinden, klicken Sie im linken Navigationsbereich der Konsole auf den Link Tools. Folgen Sie der Anleitung zum Erstellen eines Datenspeichers.

Zusätzliche Abfrageparameter

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

Mit dem Parameter filter können Sie Suchanfragen Ihrer oder unstrukturierte Daten mit Metadaten. Diese Zeichenfolge muss der unterstützte Syntax für Filterausdrücke für Datenspeicher. Mehrere Beispiele und detaillierte Beispiele wird empfohlen, das LLM des Kundenservicemitarbeiters darüber zu informieren, wie in diesen Parameter ein. Bei einem ungültigen Filterstring enthält der Filter werden beim Durchführen der Suchanfrage ignoriert.

Beispiel für einen filter-String zum Verfeinern von Suchergebnissen anhand des Standorts könnte so aussehen:

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

Best Practices zum Filtern:

Geben Sie die zum Filtern verfügbaren Felder und die gültigen Werte an für jedes dieser Felder, damit der Agent die Einschränkungen beim Erstellen gültiger Filter versteht. Beispiel: um Ergebnisse für einen Datenspeicher mit Menüinformationen zu filtern, Es könnte ein meal-Feld mit "Frühstück", "Mittagessen" und "Abendessen" geben. als gültige Werte; und ein servingSize-Feld, das eine beliebige Ganzzahl von 0 bis 5 sein kann. Ihre Anleitung könnte wie folgt 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 der Agent für eine externe Nutzerzielgruppe muss möglicherweise eine Anleitung hinzugefügt werden, damit der Kundenservicemitarbeiter der Nutzenden möglicherweise nicht mit Informationen zum Erstellen dieser Filter. 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."
```
Ein Beispiel für diesen Fall ist ebenfalls hilfreich.

Der Parameter userMetadata liefert Informationen zum Endnutzer. Beliebig Schlüssel/Wert-Paare können in diesem Parameter ausgefüllt werden. Diese Metadaten werden übergeben in das Datenspeichertool ein, um die Suchergebnisse und das Tool Antwort. Es empfiehlt sich, mehrere Beispiele zu nennen, um den LLM des Agents an, wie dieser Parameter gefüllt wird.

Beispiel für einen userMetadata-Parameterwert zum Verfeinern von Suchergebnissen für einen bestimmten Nutzer könnten wie folgt aussehen:

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

Der Parameter fallback stellt eine Antwort bereit, die das Datenspeichertool reagieren sollte wenn keine gültige zusammengefasste Antwort für die Abfrage vorhanden ist. Mehrere Beispiele können wird bereitgestellt, um das LLM des Agents anzuweisen, das Fallback für den Nutzer auszufüllen. Eingaben zu verschiedenen Themen. Es wird auch keine in der Ausgabe des Tools. Mit dieser Optimierung kann die Latenz reduziert werden. und Eingabetokens begrenzt.

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

Wenn Sie während des Tests Antworten finden, die nicht Ihren Erwartungen entsprechen, Folgende Anpassungen sind auf der Tool-Seite für ein Datenspeicher-Tool verfügbar:

Vertrauen schaffen

Für jede Antwort, die aus dem Inhalt Ihrer verbundenen Datenspeicher generiert wird, bewertet der Agent das Konfidenzniveau, Informationen in der Antwort werden durch Informationen in den Datenspeichern unterstützt. Sie können festlegen, welche Antworten zugelassen werden sollen, indem Sie die niedrigste Option auswählen das Konfidenzniveau, mit dem Sie vertraut sind. Nur Antworten, die mindestens diesem Wert entsprechen wird das Konfidenzniveau angezeigt.

Sie können zwischen fünf Konfidenzniveaus 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-Agent für die Zusammenfassung der generativen Anfrage. Wenn keines ausgewählt ist, wird ein Standardmodell wird verwendet. Die folgende Tabelle enthält die verfügbaren Optionen:

Modell-ID	Sprachunterstützung
(text-bison@002)	Die Funktion ist in allen unterstützten Sprachen verfügbar.
gemini-1.0-pro-001	Die Funktion ist in allen unterstützten Sprachen verfügbar.

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 wird der endgültige Text an das LLM gesendet.

Die Platzhalter sind wie folgt:

$original-query: Der Abfragetext des Nutzers.
$rewritten-query: Der Agent verwendet ein Rewriter-Modul zum Umschreiben. die ursprüngliche Nutzeranfrage in ein genaueres Format zu konvertieren.
$sources: Der Agent sucht mithilfe von Enterprise Search nach Quellen. basierend auf der Suchanfrage des Nutzers. 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 first source
```

$end-user-metadata: Informationen zu dem 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 gerendert:

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

Mit einer benutzerdefinierten Aufforderung sollte das LLM angewiesen werden, „NOT_ENOUGH_INFORMATION“ zurückzugeben wenn es keine Antwort geben kann. Der Agent wandelt diese Konstante in eine nutzerfreundliche Botschaft für die Nutzenden zu verfassen.

Nutzlasteinstellungen

Mit Nutzlasteinstellungen können die Datenspeicher-Snippets als Rich Content in Die Antwortnutzlast, die im messenger gerendert wird.

Gesperrte Wortgruppen (Konfiguration auf Agent-Ebene)

Sie haben die Möglichkeit, bestimmte Wortgruppen zu definieren, die nicht zulässig sind. Diese werden auf Agent-Ebene konfiguriert und sowohl vom Agent als auch LLMs und Datenspeichertools Ob die generierte Antwort oder Teile des LLM Prompts, z. B. die Eingaben des Nutzers, enthalten eine der gesperrten Formulierungen. wird diese Antwort nicht angezeigt.

Funktionstools

Wenn Ihr Clientcode auf Funktionen zugreifen kann, aber für OpenAPI-Tools nicht zugänglich sind, können Sie Funktionstools verwenden. Funktionstools werden immer clientseitig ausgeführt. nicht von der Agent-App.

So läuft der Vorgang ab:

Der Clientcode sendet eine Anfrage zur Intent-Erkennung.
Die Agent-App erkennt, dass ein Funktions-Tool erforderlich ist, und die Antwort zur Intent-Erkennung den Namen des Tools enthält. sowie Eingabeargumente. Diese Sitzung wird pausiert, bis eine weitere Anfrage zur Intent-Erkennung eingeht mit dem Toolergebnis.
Ihr Clientcode ruft das Tool auf.
Ihr Clientcode sendet eine weitere Anfrage zur Intent-Erkennung das 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 ursprüngliche Anfrage und Antwort zur Intent-Erkennung 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 zur Intent-Erkennung, und liefert das Tool-Ergebnis:

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

Clientseitige Ausführung

Wie Funktionstools, OpenAPI und Datenspeichertools kann clientseitig ausgeführt werden, indem die Anwendung einer API-Überschreibung bei der Interaktion mit der Sitzung.

Beispiel:

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

So läuft der Vorgang ab:

Ihr Clientcode sendet eine Anfrage zur Intent-Erkennung die die Clientausführung angibt.
Die Agent-App erkennt, dass ein Tool erforderlich ist, und die Antwort zur Intent-Erkennung den Namen des Tools enthält. sowie Eingabeargumente. Diese Sitzung wird pausiert, bis eine weitere Anfrage zur Intent-Erkennung eingeht mit dem Toolergebnis.
Ihr Clientcode ruft das Tool auf.
Ihr Clientcode sendet eine weitere Anfrage zur Intent-Erkennung das das Tool-Ergebnis als Ausgabeargumente bereitstellt.