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
undheader
. Der Parametertypcookie
wird noch nicht unterstützt. - Durch das OpenAPI-Schema definierte Parameter unterstützen die folgenden Datentypen:
string
,number
,integer
,boolean
,array
Der Typobject
wird noch nicht unterstützt. - Im Beispieleditor der Console können Sie derzeit 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
- 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
- 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
Der OAuth-Vorgang für die Anmeldedaten des OAuth-Clients wird für die Server-zu-Server-Authentifizierung unterstützt:
- Dieser Ablauf kann verwendet werden, wenn der Agent-Builder der Ressourceninhaber ist und keine Endnutzerautorisierung erforderlich ist.
- Client-ID, Clientschlüssel und Tokenendpunkt vom OAuth-Anbieter erforderlich die in Dialogflow konfiguriert werden soll.
- Dialogflow tauscht ein OAuth-Zugriffstoken vom OAuth-Anbieter aus und übergibt sie im auth-Header der Anfrage.
Für andere OAuth-Abläufe, die eine Endnutzerautorisierung erfordern, z. B. den Autorisierungscode-Vorgang und den PKCE-Vorgang:
- Sie müssen Ihre eigene Anmelde-UI implementieren und das Zugriffstoken auf Clientseite abrufen.
Sie haben dann folgende Möglichkeiten:
a. Verwenden Sie die Authentifizierungsoption „Inhabertoken“, um das Token an das OpenAPI-Tool zu übergeben. Dialogflow fügt dieses Token beim Aufrufen des Tools in den Autorisierungsheader ein.
b. Verwenden Sie das Funktionstool, um das Tool selbst auf Clientseite aufzurufen und das Ergebnis des Tool-Aufrufs an Dialogflow zu übergeben.
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-Projektsservicedirectory.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 einservingSize
-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 es keine gültige zusammengefasste Antwort für die Abfrage gibt. 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.