Tools

Mithilfe von Tools können Sie Agent-Anwendungen mit externen Systemen verbinden. Diese Systeme können das Wissen über Agent-Anwendungen 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.

Beschränkungen

Es gelten folgende Einschränkungen:

  • Wenn Sie ein Datenspeichertool für eine Agent-Anwendung erstellen, müssen Sie einen Datenspeicher erstellen (oder einen vorhandenen Datenspeicher verbinden).
  • 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 aktivieren, ohne dass eine manuelle Konfiguration erforderlich ist.

Folgende integrierte Tools werden unterstützt:

  • Code Interpreter: Ein eigenes Tool von Google, das die Funktionen der Codegenerierung mit der Codeausführung kombiniert und es dem Nutzer ermöglicht, verschiedene Aufgaben auszuführen, z. B. Datenanalyse, Datenvisualisierung, Textverarbeitung, Lösen von Gleichungen oder Optimierungsprobleme.

Ihre Agent-Anwendung ist optimiert, um zu bestimmen, wie und wann diese Tools aufgerufen werden sollen. Sie können jedoch zusätzliche Beispiele angeben, die zu Ihren Anwendungsfällen passen.

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 bereitstellt. Standardmäßig ruft die Agent-Anwendung 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 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.
  • Vom OpenAPI-Schema definierte Parameter unterstützen die folgenden Datentypen: string, number, integer, boolean, array. Der Typ object wird noch nicht unterstützt.
  • Im Beispieleditor der Konsole können Sie derzeit keine Abfrageparameter angeben.
  • Der Anfrage- und Antworttext muss leer oder JSON sein.

API-Authentifizierung des OpenAPI-Tools

Die folgenden Authentifizierungsoptionen werden beim Aufrufen einer externen API unterstützt:

  • Authentifizierung des Dialogflow-Dienst-Agents
    • Dialogflow kann mit dem Dialogflow-Dienst-Agent ein ID-Token oder Zugriffstoken generieren. Das Token wird dem Autorisierungs-HTTP-Header hinzugefügt, wenn Dialogflow eine externe API aufruft.
    • Ein ID-Token kann für den Zugriff auf Cloud Functions- 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 gewährt haben. Wenn sich die Cloud Functions- und Cloud Run-Dienste im selben Ressourcenprojekt befinden, benötigen Sie für den Aufruf keine zusätzliche IAM-Berechtigung.
    • Mit einem Zugriffstoken kann auf andere Google Cloud APIs zugegriffen werden, nachdem Sie service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com die erforderlichen Rollen gewährt haben.
  • API-Schlüssel
    • Zum Konfigurieren der API-Schlüsselauthentifizierung können Sie den Schlüsselnamen, den Ort der Anfrage (Header oder Abfragestring) und den API-Schlüssel angeben, damit Dialogflow den API-Schlüssel in der Anfrage übergibt.
  • OAuth
    • Der OAuth-Client-Anmeldedatenfluss wird für die Server-zu-Server-Authentifizierung unterstützt. Die Client-ID, der Clientschlüssel und der Tokenendpunkt des OAuth-Anbieters 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 Functions-Tool verwenden, um das Token in Ihre eigene Anmelde-UI einzubinden.
  • Gegenseitige TLS-Authentifizierung
  • Benutzerdefiniertes CA-Zertifikat

Datenspeichertools

Datenspeichertools können von einer Agent-Anwendung verwendet werden, um aus Ihren Datenspeichern Antworten auf Endnutzerfragen zu erhalten. Sie können pro Typ einen Datenspeicher einrichten. Das Tool fragt dann jeden 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.

Folgende Typen von Datenspeichern sind möglich:

  • 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 auf einen Datenspeicher verwiesen wird:

"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. Die Agent-App kann weitere Anweisungen zur weiteren Vorgehensweise bei der Antwort aus den Datenspeichern geben oder dazu, wie zu reagieren ist, wenn es keine Antwort gibt.

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

Beispiele können verwendet werden, um das Verhalten der Agent-Anwendung 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, verwenden Sie den Link Tools im linken Navigationsbereich der Console. Folgen Sie der Anleitung zum Erstellen eines Datenspeichers.

Zusätzliche Abfrageparameter

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

Mit dem Parameter filter können Sie Suchanfragen nach Ihren strukturierten Daten oder unstrukturierten Daten mit Metadaten filtern. Dieser String muss der unterstützten Syntax für Filterausdrücke entsprechen. Es werden mehrere Beispiele empfohlen, um dem Agent-LLM mitzuteilen, wie dieser Parameter ausgefüllt werden soll. Ist ein ungültiger Filterstring vorhanden, wird der Filter beim Ausführen der Suchanfrage ignoriert.

Ein filter-String zum Verfeinern von Suchergebnissen basierend auf dem Standort könnte beispielsweise so aussehen:

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

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 die Suchergebnisse und die Antwort des Tools besser zu informieren. Es empfiehlt sich, mehrere Beispiele anzugeben, um das Agent-LLM anzuweisen, wie dieser Parameter eingefügt wird.

Ein Beispiel für einen userMetadata-Parameterwert zur Verfeinerung der Suchergebnisse, die für einen bestimmten Nutzer relevant sind, könnte so aussehen:

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

Wenn Sie während des Tests feststellen, dass einige Antworten Ihre Erwartungen nicht erfüllen, sind auf der Tool-Seite die folgenden Anpassungen für ein Datenspeichertool verfügbar:

Solidität

Für jede Antwort, die aus dem Inhalt Ihrer verbundenen Datenspeicher generiert wurde, bewertet der Agent ein Konfidenzniveau. Damit wird die Konfidenz beurteilt, ob alle Informationen in der Antwort durch Informationen in den Datenspeichern gestützt werden. Sie können anpassen, 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 entsprechen 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 Zusammenfassungsanfrage verwendet wird. Wenn keine Option ausgewählt ist, wird eine Standardmodelloption verwendet. Die folgende Tabelle enthält die verfügbaren Optionen:

Modellkennzeichnung Sprachunterstützung
text-bison@001 Diese Funktion ist in allen unterstützten Sprachen verfügbar.
(text-bison@002) Diese Funktion ist in allen unterstützten Sprachen verfügbar.
text-bison@001 abgestimmt (konversationell) Derzeit werden nur Englisch unterstützt.
text-bison@001 abgestimmt (informativ) Derzeit werden nur Englisch unterstützt.
Zwillinge-Pro Diese Funktion ist in allen unterstützten Sprachen verfügbar.

Sie können auch einen eigenen Prompt für den LLM-Zusammenfassungsaufruf 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:

  • $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 verwendet Enterprise Search, um anhand der Nutzerabfrage 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 first source

  • $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

Eine benutzerdefinierte Aufforderung sollte das LLM anweisen, „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)

Du hast 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 den Datenspeichertools verwendet. Wenn die generierte Antwort oder Teile der LLM-Aufforderung, z. B. die Eingaben des Nutzers, eine der gesperrten Wortgruppen enthalten, wird diese Antwort nicht angezeigt.

Funktionstools

Wenn Funktionen mit Ihrem Clientcode, aber nicht mit OpenAPI-Tools zugänglich sind, können Sie Funktionstools verwenden. Funktionstools werden immer clientseitig ausgeführt, nicht von der Agent-Anwendung.

So läuft der Vorgang ab:

  1. Ihr 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 die Eingabeargumente. Diese Sitzung wird pausiert, bis eine weitere Anfrage zur Intent-Erkennung mit dem Toolergebnis eingeht.
  3. Das Tool wird über Ihren Clientcode aufgerufen.
  4. Ihr 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 erste 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, bei der das Toolergebnis zurückgegeben wird:

{
  "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. Ihr Clientcode sendet eine Anfrage zur Intent-Erkennung, die die Clientausführung angibt.
  2. Die Agent-Anwendung erkennt, dass ein Tool erforderlich ist, und die Antwort zur Intent-Erkennung enthält den Namen des Tools sowie die Eingabeargumente. Diese Sitzung wird pausiert, bis eine weitere Anfrage zur Intent-Erkennung mit dem Toolergebnis eingeht.
  3. Das Tool wird über Ihren Clientcode aufgerufen.
  4. Ihr Clientcode sendet eine weitere Anfrage zur Intent-Erkennung, die das Toolergebnis als Ausgabeargumente bereitstellt.
Zurück
Best Practices
Weiter
Überblick