Con gli strumenti, puoi collegare i playbook a sistemi esterni. Questi sistemi possono aumentare le conoscenze dei playbook e consentire loro di eseguire attività complesse in modo efficiente.
Puoi utilizzare gli strumenti integrati o crearne di personalizzati in base alle tue esigenze.
Limitazioni
Si applicano le seguenti limitazioni:
- Devi creare un datastore (o collegarne uno esistente) quando crei uno strumento di datastore per un agente.
- Le app con datastore suddivisi in blocchi e non suddivisi in blocchi non sono supportate.
Strumenti integrati
Gli strumenti integrati sono ospitati da Google. Puoi attivare questi strumenti negli agenti senza bisogno di configurazione manuale.
Gli strumenti integrati supportati sono:
Code Interpreter: uno strumento proprietario di Google che combina la capacità di generazione e di esecuzione del codice e consente all'utente di eseguire varie attività, tra cui analisi dei dati, visualizzazione dei dati, elaborazione di testo, risoluzione di equazioni o problemi di ottimizzazione.
L'agente è ottimizzato per determinare come e quando devono essere richiamati questi strumenti, ma puoi fornire esempi aggiuntivi in base ai tuoi casi d'uso.
Gli esempi devono avere uno schema come il seguente:
{
"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"
}
}
]
}
}
Strumenti OpenAPI
Un agente può connettersi a un'API esterna utilizzando uno strumento OpenAPI fornendo lo schema OpenAPI. Per impostazione predefinita, l'agente chiamerà l'API per tuo conto. In alternativa, puoi eseguire gli strumenti OpenAPI sul lato client.
Schema di esempio:
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
Facoltativamente, puoi utilizzare il riferimento allo schema interno @dialogflow/sessionId
come tipo di schema del parametro.
Con questo tipo di schema dei parametri,
l'ID sessione Dialogflow per la conversazione corrente
verrà fornito come valore parametro.
Ad esempio:
- name: X-SESSION
in: header
description: Dialogflow session id
required: false
schema:
$ref: "@dialogflow/sessionId"
Limitazioni dello strumento OpenAPI
Si applicano le seguenti limitazioni:
- I tipi di parametri supportati sono
path,query,header. Il tipo di parametrocookienon è ancora supportato. - I parametri definiti dallo schema OpenAPI supportano i seguenti tipi di dati:
string,number,integer,boolean,array. Il tipoobjectnon è ancora supportato. - Al momento non puoi specificare parametri di ricerca nell'editor di esempi della console.
- Il corpo della richiesta e della risposta deve essere vuoto o JSON.
Autenticazione API dello strumento OpenAPI
Quando chiami un'API esterna, sono supportate le seguenti opzioni di autenticazione:
- Auth dell'agente di servizio Dialogflow
- Dialogflow può generare un token ID o un token di accesso utilizzando l'agente di servizio Dialogflow. Il token viene aggiunto nell'intestazione HTTP di autorizzazione quando Dialogflow chiama un'API esterna.
- Un token ID può essere utilizzato per accedere alle funzioni e ai servizi Cloud Run dopo aver concesso i ruoli roles/cloudfunctions.invoker e roles/run.invoker a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Se le funzioni e i servizi Cloud Run si trovano nello stesso progetto di risorse, non è necessaria un'autorizzazione IAM aggiuntiva per richiamarli.
- Un token di accesso può essere utilizzato per accedere ad altre API Google Cloud dopo aver assegnato i ruoli richiesti a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
- Chiave API
- Puoi configurare l'autenticazione con chiave API fornendo il nome della chiave, la posizione della richiesta (intestazione o stringa di query) e la chiave API in modo che Dialogflow trasmetta la chiave API nella richiesta.
OAuth
Il flusso delle credenziali client OAuth è supportato per l'autenticazione server-to-server:
- Questo flusso può essere utilizzato se la console di Agent Builder è il proprietario della risorsa e non è necessaria l'autorizzazione dell'utente finale.
- L'ID client, il client secret e l'endpoint del token del provider OAuth devono essere configurati in Dialogflow.
- Dialogflow scambia un token di accesso OAuth dal fornitore OAuth e lo passa nell'intestazione di autenticazione della richiesta.
Per altri flussi OAuth che richiedono l'autorizzazione dell'utente finale, come il flusso del codice di autorizzazione e il flusso PKCE:
- Dovrai implementare la tua UI di accesso e ottenere il token di accesso lato client.
A questo punto puoi:
a. Utilizza l'opzione di autenticazione con token bearer per passare il token allo strumento OpenAPI. Dialogflow includerà questo token nell'intestazione di autorizzazione quando invoca lo strumento.
b. Utilizza lo strumento Funzione per richiamare lo strumento sul lato client e passare il risultato della chiamata dello strumento a Dialogflow.
Token di connessione
- Puoi configurare l'autenticazione Bearer per trasmettere dinamicamente il token Bearer dal client. Questo token è incluso nell'intestazione di autenticazione della richiesta.
- Quando configuri l'autenticazione dello strumento, puoi designare un parametro di sessione come token di accesso. Ad esempio, utilizza
$session.params.<parameter-name-for-token>per specificare il token. - In fase di esecuzione, assegna il token Bearer al parametro session:
DetectIntentRequest { ... query_params { parameters { <parameter-name-for-token>: <the-auth-token> } } ... }Autenticazione TLS reciproca
- Consulta la documentazione sull'autenticazione TLS reciproca.
- I certificati client personalizzati sono supportati. Puoi configurare i certificati client a livello di agente nella scheda Sicurezza delle impostazioni dell'agente. Il certificato (formato PEM) e la chiave privata (formato PEM) sono campi obbligatori. Una volta impostato, questo certificato client verrà utilizzato durante TLS reciproco per tutti gli strumenti e gli webhook.
Certificato CA personalizzato
- Consulta la documentazione relativa ai certificati CA personalizzati.
Accesso alla rete privata dello strumento OpenAPI
Lo strumento OpenAPI si integra con l'accesso alla rete privata di Service Directory, pertanto può connettersi ai target API all'interno della rete VPC. In questo modo, il traffico rimane all'interno della rete Google Cloud e vengono applicati IAM e Controlli di servizio VPC.
Per configurare uno strumento OpenAPI che ha come target una rete privata:
Segui la configurazione della rete privata di Service Directory per configurare la rete VPC e l'endpoint di Service Directory.
Per il progetto dell'agente deve esistere l'account di servizio Agente di servizio Dialogflow con il seguente indirizzo:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
servicedirectory.viewerdel progetto Service Directoryservicedirectory.pscAuthorizedServicedel progetto di rete
Fornisci il servizio Service Directory insieme allo schema OpenAPI e alle informazioni di autenticazione facoltative durante la creazione dello strumento.
Accesso ai parametri di sessione dello strumento OpenAPI
Gli input dello strumento Open API vengono ricavati dalla conversazione degli utenti con l'LLM utilizzando lo schema come guida. In alcuni casi, gli input potrebbero dover essere ricavati dai parametri della sessione raccolti durante un flusso o forniti come input del parametro di query insieme all'input utente.
Il parametro sessione che deve essere passato come input può essere specificato come
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.
Se non è disponibile un parametro di sessione di questo tipo, l'input generato dall'LLM verrà passato allo strumento.
Valori predefiniti dello strumento OpenAPI
Lo schema dell'API Open può essere utilizzato per specificare i valori predefiniti. I valori predefiniti vengono utilizzati solo se non è presente un valore di input generato da LLM o un valore di input basato sul parametro della sessione per quel parametro o quella proprietà.
I valori predefiniti possono essere specificati all'interno dello schema come segue:
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
Se non è presente alcun valore generato da LLM, valore parametro di sessione o valore predefinito, l'input non sarà specificato.
Strumenti per i datastore
Gli strumenti dei datastore possono essere utilizzati da un agente per rispondere alle domande degli utenti finali provenienti dai tuoi datastore. Puoi configurare un datastore di ogni tipo per strumento, e lo strumento eseguirà query su ciascuno di questi data store per trovare le risposte. Per impostazione predefinita, l'agente chiamerà lo strumento datastore per tuo conto. In alternativa, puoi eseguire gli strumenti del datastore sul lato client.
Il tipo di datastore può essere uno dei seguenti:
PUBLIC_WEB: un datastore contenente contenuti web pubblici.UNSTRUCTURED: un datastore contenente dati privati non strutturati.STRUCTURED: un datastore contenente dati strutturati (ad es. domande frequenti).
L'esempio seguente mostra come fare riferimento a un datastore:
"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"
}
]
Le risposte dello strumento del datastore possono contenere anche snippet sull'origine dei contenuti che è stata utilizzata per generare la risposta. L'agente può fornire ulteriori istruzioni su come procedere con la risposta degli archivi dati o su come rispondere quando non c'è risposta.
Puoi sovrascrivere una risposta aggiungendo una voce della sezione Domande frequenti per una domanda specifica.
Gli esempi possono essere utilizzati per migliorare ulteriormente il comportamento dell'agente. L'esempio deve avere i seguenti schemi:
{
"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"
}
]
}
}
]
}
}
Crea un datastore
Per creare un datastore e collegarlo alla tua app, puoi utilizzare il link Strumenti nel riquadro di navigazione a sinistra della console. Segui le istruzioni per creare un datastore.
Parametri di ricerca aggiuntivi
Quando crei esempi di strumenti per l'datastore, il parametro di input dello strumento requestBody
fornisce tre input facoltativi insieme alla stringa query obbligatoria:
una stringa filter, un oggetto strutturato userMetadata e una stringa fallback.
Il parametro filter consente di filtrare le query di ricerca dei tuoi
dati strutturati o non strutturati con i metadati. Questa stringa deve rispettare la
sintassi delle espressioni filtro supportate
per i datastore.
È consigliabile fornire più esempi ed esempi dettagliati per indicare al modello LLM del playbook come compilare questo parametro. In caso di stringa di filtro non valida, il filtro verrà ignorato durante l'esecuzione della query di ricerca.
Un esempio di stringa filter per perfezionare i risultati di ricerca in base alla località potrebbe essere:
"filter": "country: ANY(\"Canada\")"
Best practice per i filtri:
Specifica i campi disponibili per il filtro e i valori validi per ciascuno di questi campi, in modo che il playbook comprenda le limitazioni per la creazione di filtri validi. Ad esempio, per filtrare i risultati di un datastore contenente informazioni sul menu, potrebbe essere presente un campo
mealcon "colazione", "pranzo" e "cena" come valori validi e un camposervingSizeche può essere un qualsiasi numero intero compreso tra 0 e 5. Le istruzioni potrebbero avere il seguente aspetto: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.Se il playbook è destinato a un pubblico di utenti esterni, potrebbe essere necessario aggiungere istruzioni per impedire al playbook di rispondere all'utente con informazioni sulla creazione di questi filtri. Ad esempio:
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."Fornire un esempio di questo caso è utile.
Il parametro userMetadata fornisce informazioni sull'utente finale. In questo parametro è possibile inserire qualsiasi coppia chiave-valore. Questi metadati vengono trasmessi allo strumento dell'datastore per fornire informazioni più dettagliate sui risultati di ricerca e sulla risposta dello strumento. Ti consigliamo di fornire più esempi per indicare all'LLM del playbook come compilare questo parametro.
Un esempio di valore parametro userMetadata per perfezionare i risultati di ricerca pertinenti per un utente specifico potrebbe essere:
"userMetadata": {
"favoriteColor": "blue",
...
}
Il parametro fallback fornisce una risposta con cui lo strumento dell'datastore deve rispondere se non esiste una risposta riepilogativa valida per la query. È possibile fornire più esempi per indicare all'LLM del playbook come compilare il valore predefinito per gli input degli utenti relativi a diversi argomenti. Inoltre, non saranno presenti snippet nell'output dello strumento. Questa ottimizzazione può essere utilizzata per ridurre la latenza
e l'utilizzo del limite di token di input.
"fallback": "I'm sorry I cannot help you with that. Is there anything else I
can do for you?"
Se durante il test alcune risposte non soddisfano le tue aspettative, nella pagina dello strumento per un datastore sono disponibili le seguenti personalizzazioni:
Rafforzare la fiducia
Per ogni risposta generata dai contenuti dei tuoi datastore collegati, il playbook valuta un livello di confidenza, che misura la certezza che tutte le informazioni nella risposta siano supportate dalle informazioni nei datastore. Puoi personalizzare le risposte consentite selezionando il livello di confidenza più basso che ritieni accettabile. Verranno mostrate solo le risposte con un livello di confidenza pari o superiore a questo.
Puoi scegliere tra 5 livelli di confidenza: VERY_LOW, LOW, MEDIUM,
HIGH e VERY_HIGH.
Configurazione del riassunto
Puoi selezionare il modello generativo utilizzato da un gestore datastore per la richiesta di generazione di riepiloghi. Se non viene selezionato nessuno, viene utilizzata un'opzione di modello predefinita. La tabella seguente contiene le opzioni disponibili:
| Identificatore modello | Supporto delle lingue |
|---|---|
| text-bison@002 | Disponibile in tutte le lingue supportate. |
| gemini-1.0-pro-001 | Disponibile in tutte le lingue supportate. |
Puoi anche fornire il tuo prompt per la chiamata LLM di sintesi.
Il prompt è un modello di testo che può contenere segnaposto predefiniti. I segnaposto verranno sostituiti con i valori appropriati in fase di esecuzione e il testo finale verrà inviato all'LLM.
I segnaposto sono i seguenti:
$original-query: il testo della query dell'utente.$rewritten-query: il playbook utilizza un modulo di riscrittura per riscrivere la query utente originale in un formato più preciso.$sources: il playbook utilizza Enterprise Search per cercare le origini in base alla query dell'utente. Le origini trovate vengono visualizzate in un formato specifico:[1] title of first source content of first source [2] title of second source content of second source$end-user-metadata: le informazioni sull'utente che invia la query vengono visualizzate nel seguente formato:The following additional information is available about the human: { "key1": "value1", "key2": "value2", ... }$conversation: la cronologia della conversazione viene visualizzata nel seguente formato:Human: user's first query AI: answer to user's first query Human: user's second query AI: answer to user's second query
Un prompt personalizzato deve indicare all'LLM di restituire "NOT_ENOUGH_INFORMATION" quando non può fornire una risposta. Il playbook trasformerà questa costante in un messaggio intuitivo per l'utente.
Impostazioni del payload
Le impostazioni del payload consentono di aggiungere gli snippet datastore come contenuti avanzati nel payload della risposta visualizzato nel messenger.
Frasi vietate (configurazione a livello di playbook)
Hai la possibilità di definire frasi specifiche che non devono essere consentite. Questi vengono configurati a livello di playbook e utilizzati sia dagli LLM di playbook sia dagli strumenti di datastore. Se la risposta generata o parti del prompt LLM, come gli input dell'utente, contengono una delle frasi vietate, la risposta non verrà mostrata.
Strumenti di funzione
Se hai funzionalità accessibili dal codice client, ma non dagli strumenti OpenAPI, puoi utilizzare gli strumenti di funzione. Gli strumenti di funzione vengono sempre eseguiti sul lato client, non dall'agente.
La procedura è la seguente:
- Il codice client invia una richiesta di rilevamento dell'intenzione.
- L'agente rileva che è necessario uno strumento di funzione e la risposta al rilevamento dell'intenzione contiene il nome dello strumento insieme agli argomenti di input. Questa sessione viene messa in pausa fino a quando non viene ricevuta un'altra richiesta di rilevamento dell'intenzione con il risultato dello strumento.
- Il codice client chiama lo strumento.
- Il codice client invia un'altra richiesta di rilevamento dell'intenzione che fornisce il risultato dello strumento come argomenti di output.
L'esempio seguente mostra lo schema di input e output di uno strumento di funzione:
{
"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"
}
}
}
L'esempio seguente mostra la richiesta e la risposta iniziali di rilevamento dell'intenzione utilizzando 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"
}
}
}
]
}
}
L'esempio seguente mostra la seconda richiesta di rilevamento dell'intenzione, che fornisce il risultato dello strumento:
{
"queryInput": {
"toolCallResult": {
"tool": "<tool-resource-name>",
"action": "get-weather-tool",
"outputParameters": {
"temperature": 28.0
}
},
"languageCode": "en"
}
}
Esecuzione lato client
Come gli strumenti di funzione, gli strumenti OpenAPI e di datastore possono essere eseguiti lato client applicando una sostituzione dell'API quando interagisci con la sessione.
Ad esempio:
DetectIntentRequest {
...
query_params {
playbook_state_override {
playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
}
}
...
}
La procedura è la seguente:
- Il codice client invia una richiesta di rilevamento dell'intenzione che specifica l'esecuzione del client.
- L'agente rileva che è necessario uno strumento e la risposta al rilevamento dell'intento contiene il nome dello strumento insieme agli argomenti di input. Questa sessione viene messa in pausa fino a quando non viene ricevuta un'altra richiesta di rilevamento dell'intenzione con il risultato dello strumento.
- Il codice client chiama lo strumento.
- Il codice client invia un'altra richiesta di rilevamento dell'intenzione che fornisce il risultato dello strumento come argomenti di output.