Tools

Mithilfe von Tools können Sie Agent-Anwendungen mit externen Systemen verbinden. Diese Systeme können das Wissen über Agent-Anwendungen erweitern und ihnen die Möglichkeit geben, komplexe Aufgaben effizient auszuführen.

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

Beschränkungen

Es gelten folgende Einschränkungen:

  • Sie müssen einen Datenspeicher erstellen (oder einen vorhandenen Datenspeicher verbinden), wenn Sie ein Datenspeichertool für eine Agent-Anwendung erstellen.
  • Anwendungen mit aufgeteilten und nicht aufgeteilten Datenspeichern werden nicht unterstützt.

Integrierte Tools

Integrierte Tools werden von Google gehostet. Sie können diese Tools in Agent-Anwendungen ohne manuelle Konfiguration aktivieren.

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-Anwendung ist so optimiert, dass festgelegt wird, wie und wann diese Tools aufgerufen werden sollen. Sie können jedoch 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. Dazu stellt sie das OpenAPI-Schema bereit. Standardmäßig ruft die Agent-Anwendung 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 als Parameterschematyp verwenden. Bei diesem Parameterschematyp wird 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 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 im JSON-Format sein.

API-Authentifizierung des OpenAPI-Tools

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

  • Authentifizierung des Dialogflow-Dienst-Agents
    • Dialogflow kann mit dem Dialogflow-Dienst-Agent ein ID-Token oder ein Zugriffstoken generieren. 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 service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com die Rollen roles/cloudfunctions.invoker und roles/run.invoker gewährt haben. 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 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 zugewiesen haben.
  • API-Schlüssel
    • Sie können die API-Schlüsselauthentifizierung konfigurieren, indem Sie den Schlüsselnamen, den Anfrageort (Header oder Abfragestring) und den API-Schlüssel angeben, damit Dialogflow den API-Schlüssel in der Anfrage übergibt.
  • OAuth
    • 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 müssen in Dialogflow konfiguriert werden. Dialogflow tauscht ein OAuth-Zugriffstoken aus und übergibt es im Auth-Header der Anfrage.
    • Bei anderen OAuth-Abläufen müssen Sie das Funktionstool verwenden, um es in Ihre eigene Anmelde-UI einzubinden und das Token auszutauschen.

  • Inhabertoken

    • Sie können die Inhaberauthentifizierung so konfigurieren, dass das Inhabertoken dynamisch vom Client übergeben wird. Dieses Token ist im auth-Header der Anfrage enthalten.
    • Beim Einrichten der Tool-Authentifizierung können Sie einen Sitzungsparameter festlegen, der als Inhabertoken dient. 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

  • Benutzerdefiniertes CA-Zertifikat

Privater Netzwerkzugriff mit OpenAPI-Tool

Das OpenAPI-Tool lässt sich in den privaten Netzwerkzugriff auf Service Directory einbinden, sodass es eine Verbindung zu API-Zielen in Ihrem VPC-Netzwerk herstellen 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:

  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 des Dialogflow-Dienst-Agents mit der folgenden Adresse muss 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

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

Datenspeichertools

Datenspeichertools können von einer Agent-Anwendung für Antworten auf Endnutzerfragen aus Ihren Datenspeichern verwendet werden. Sie können für jeden Typ einen Datenspeicher pro Tool einrichten. Das Tool fragt dann in jedem dieser Datenspeicher nach Antworten ab. Standardmäßig ruft die Agent-Anwendung 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 über die Contentquelle enthalten, die zum Generieren der Antwort verwendet wurde. Die Agent-App kann außerdem eine Anleitung zum weiteren Vorgehen mit der Antwort aus den Datenspeichern bereitstellen oder dazu, wie zu antworten ist, wenn es keine Antwort gibt.

Sie können eine Antwort überschreiben, indem Sie einen FAQ-Eintrag zu einer bestimmten Frage hinzufügen.

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 Anwendung zu verbinden, können Sie den Link Tools im linken Navigationsbereich der Console verwenden. Folgen Sie der Anleitung zum Erstellen eines Datenspeichers.

Zusätzliche Abfrageparameter

Beim Erstellen von Beispielen für ein Datenspeichertool stehen neben dem erforderlichen query-String zwei optionale Parameter zur Verfügung: ein filter-String und ein strukturiertes userMetadata-Objekt.

Mit dem Parameter filter können Sie Suchanfragen Ihrer strukturierten oder unstrukturierten Daten mit Metadaten filtern. Dieser String muss der unterstützten Syntax für Filterausdrücke für Datenspeicher entsprechen. Es wird empfohlen, mehrere und detaillierte Beispiele zu verwenden, um dem Agent-LLM mitzuteilen, wie dieser Parameter ausgefüllt werden soll. Bei einem ungültigen Filterstring wird der Filter bei der Suchanfrage ignoriert.

Ein filter-String zum Verfeinern der Suchergebnisse anhand des Standorts könnte beispielsweise so aussehen:

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

Best Practices zum Filtern:

  • Geben Sie die zum Filtern verfügbaren Felder und die gültigen Werte für jedes dieser Felder an, sodass der Agent die Einschränkungen zum Erstellen gültiger Filter versteht. Um beispielsweise Ergebnisse für einen Datenspeicher mit Menüinformationen zu filtern, könnte ein meal-Feld mit gültigen Werten für "Frühstück", "Mittagessen" und "Abendessen" und ein servingSize-Feld vorhanden sein, 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 vorgesehen ist, müssen Sie möglicherweise Anweisungen hinzufügen, damit der Agent dem Nutzer möglicherweise keine Informationen zum Erstellen dieser Filter sendet. 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. In diesem Parameter können alle Schlüssel/Wert-Paare ausgefüllt werden. Diese Metadaten werden an das Datenspeichertool übergeben, um bessere Suchergebnisse und Tool-Antworten zu liefern. Es wird empfohlen, mehrere Beispiele anzugeben, um das Agent-LLM anzuweisen, wie dieser Parameter ausgefüllt wird.

Ein userMetadata-Parameterwert zum Verfeinern von Suchergebnissen, die für einen bestimmten Nutzer relevant sind, könnte beispielsweise so aussehen:

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

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

Vertrauen schaffen

Für jede Antwort, die aus dem Inhalt Ihrer verbundenen Datenspeicher generiert wird, wertet der Agent ein Konfidenzniveau aus. Damit wird die Wahrscheinlichkeit bewertet, dass alle Informationen in der Antwort von Informationen in den Datenspeichern unterstützt werden. Sie können festlegen, welche Antworten zugelassen werden sollen, indem Sie das niedrigste Konfidenzniveau auswählen, das für Sie akzeptabel ist. Es werden nur Antworten angezeigt, die diesem Konfidenzniveau oder darüber liegen.

Es stehen fünf Konfidenzniveaus zur Auswahl: 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 generative Anfrage zur Zusammenfassung verwendet wird. Wenn keiner ausgewählt ist, wird eine Standardmodelloption 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 der endgültige Text wird an das LLM gesendet.

Die Platzhalter sind wie folgt:

  • $original-query: Der Abfragetext des Nutzers.
  • $rewritten-query: Der Agent verwendet ein Rewriter-Modul, um die ursprüngliche Nutzerabfrage in ein genaueres Format umzuschreiben.

  • $sources: Der Agent sucht mithilfe von Enterprise Search nach Quellen basierend auf der Abfrage 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 keine Antwort möglich ist. Der Agent wandelt diese Konstante in eine nutzerfreundliche Nachricht für den Nutzer um.

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 von den Agent-LLMs als auch von den Datenspeichertools verwendet. Wenn die generierte Antwort oder Teile der LLM-Eingabeaufforderung, z. B. die Eingaben des Nutzers, eine der gesperrten Wortgruppen wortwörtlich enthalten, wird diese Antwort nicht angezeigt.

Funktionstools

Wenn über Ihren Clientcode Funktionen verfügbar sind, die für OpenAPI-Tools aber 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:

  1. Der Clientcode sendet eine Anfrage zur Intent-Erkennung.
  2. Die Agent-Anwendung 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 Anfrage zur Intent-Erkennung mit dem Ergebnis des Tools eingeht.
  3. Ihr Clientcode ruft das Tool auf.
  4. Der Clientcode sendet eine weitere Anfrage zur Intent-Erkennung, die das Toolergebnis 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, die das Toolergebnis liefert:

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

Clientseitige Ausführung

Wie Funktionstools können OpenAPI- und Datenspeichertools clientseitig 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. Der Clientcode sendet eine Anfrage zur Intent-Erkennung, in der die Ausführung des Clients angegeben wird.
  2. Die Agent-Anwendung erkennt, dass ein Tool erforderlich ist, und die Antwort zur Intent-Erkennung enthält den Namen des Tools sowie Eingabeargumente. Diese Sitzung wird pausiert, bis eine weitere Anfrage zur Intent-Erkennung mit dem Ergebnis des Tools eingeht.
  3. Ihr Clientcode ruft das Tool auf.
  4. Der Clientcode sendet eine weitere Anfrage zur Intent-Erkennung, die das Toolergebnis als Ausgabeargumente bereitstellt.
Zurück
Benutzeroberfläche
Weiter
Best Practices