Utilizzando gli strumenti, puoi connettere le app degli agenti a sistemi esterni. Questi sistemi possono aumentare la conoscenza delle app degli agenti e consentire loro di eseguire attività complesse in modo efficiente.
Puoi usare strumenti integrati o creare strumenti personalizzati in base alle tue esigenze.
Limitazioni
Si applicano le seguenti limitazioni:
- Devi creare un datastore (o connettere un datastore esistente) quando crei uno strumento di datastore per un'app agente.
- Le app con datastore a blocchi e non a blocchi non sono supportate.
Strumenti integrati
Gli strumenti integrati sono ospitati da Google. Puoi attivare questi strumenti nelle app agente senza dover configurare manualmente.
Gli strumenti integrati supportati sono:
Code Interpreter: uno strumento proprietario di Google che combina le funzionalità di generazione ed esecuzione di 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.
La tua app dell'agente è ottimizzata per determinare come e quando questi strumenti devono essere richiamati, ma puoi fornire esempi aggiuntivi per adattarli ai tuoi casi d'uso.
Gli esempi devono avere uno schema simile al 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'app agente può connettersi a un'API esterna utilizzando uno strumento OpenAPI fornendo lo schema OpenAPI. Per impostazione predefinita, l'app dell'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 dello schema interno @dialogflow/sessionId come tipo di schema dei parametri.
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,queryeheader. 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 esempio della console.
- Il corpo della richiesta e della risposta deve essere vuoto o in formato JSON.
Autenticazione API dello strumento OpenAPI
Quando chiami un'API esterna, sono supportate le seguenti opzioni di autenticazione:
- Autorizzazione 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.
- Puoi utilizzare un token ID per accedere ai servizi Cloud Functions e 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 i servizi Cloud Functions e Cloud Run si trovano nello stesso progetto di risorsa, non è necessaria un'autorizzazione IAM aggiuntiva per chiamarli.
- Puoi utilizzare un token di accesso per accedere ad altre API Google Cloud dopo aver concesso 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 località della richiesta (intestazione o stringa di query) e la chiave API in modo che Dialogflow passi la chiave API nella richiesta.
- OAuth
- Il flusso di credenziali client OAuth è supportato per l'autenticazione server-to-server. ID client, client secret ed endpoint token del provider OAuth devono essere configurati in Dialogflow. Dialogflow scambia un token di accesso OAuth e lo passa nell'intestazione auth della richiesta.
- Per altri flussi OAuth, devi utilizzare lo strumento Funzioni per l'integrazione con la tua interfaccia utente di accesso per lo scambio del token.
Token di connessione
- Puoi configurare l'autenticazione di connessione per passare dinamicamente il token di connessione dal client. Questo token è incluso nell'intestazione auth della richiesta.
- Quando configuri l'autenticazione dello strumento, puoi specificare un parametro di sessione
che funga da token di connessione. Ad esempio, utilizza
$session.params.<parameter-name-for-token>per specificare il token. - In fase di runtime, assegna il token di connessione al parametro di sessione:
DetectIntentRequest { ... query_params { parameters { <parameter-name-for-token>: <the-auth-token> } } ... }Autenticazione TLS reciproca
- Consulta la documentazione sull'autenticazione TLS reciproca.
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, così può connettersi alle destinazioni delle API all'interno della tua rete VPC. In questo modo il traffico viene mantenuto all'interno della rete Google Cloud e vengono applicati IAM e Controlli di servizio VPC.
Per impostare 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 dell'agente di servizio Dialogflow con il seguente indirizzo:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Concedi all'account di servizio dell'agente di servizio Dialogflow i seguenti ruoli IAM: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.
Strumenti per datastore
Gli strumenti del datastore possono essere utilizzati dall'app agente per rispondere alle domande dell'utente finale dai tuoi datastore. Puoi configurare un datastore di ogni tipo per strumento e lo strumento eseguirà query su ciascuno di questi datastore per trovare le risposte. Per impostazione predefinita, l'app dell'agente chiama lo strumento datastore per tuo conto. In alternativa, puoi eseguire strumenti per datastore sul lato client.
Il tipo di datastore può essere uno dei seguenti:
PUBLIC_WEB: un datastore con contenuti web pubblici.UNSTRUCTURED: un datastore che contiene dati privati non strutturati.STRUCTURED: un datastore che contiene dati strutturati (ad esempio domande frequenti).
Nell'esempio seguente viene illustrato 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 potrebbero contenere anche snippet relativi all'origine di contenuto utilizzata per generare la risposta. L'app dell'agente può fornire ulteriori istruzioni su come procedere con la risposta dai datastore o su come rispondere in assenza di risposta.
Puoi sovrascrivere una risposta aggiungendo una voce delle domande frequenti per una domanda specifica.
Gli esempi possono essere utilizzati per migliorare ulteriormente il comportamento dell'app dell'agente. L'esempio dovrebbe 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 menu di navigazione a sinistra della console. Segui le istruzioni per creare un datastore.
Parametri di ricerca aggiuntivi
Quando crei esempi di strumenti del 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 dati strutturati o dei dati non strutturati con metadati. Questa stringa deve rispettare la sintassi supportata delle espressioni di filtro per i datastore.
Ti invitiamo a fornire esempi multipli ed esempi dettagliati
per indicare all'LLM dell'agente come
compilare questo parametro. Nel caso di stringa di filtro non valida, il filtro verrà ignorato quando esegui la query di ricerca.
Un esempio di stringa filter per perfezionare i risultati di ricerca in base alla località potrebbe avere il seguente aspetto:
"filter": "country: ANY(\"Canada\")"
Best practice per l'applicazione di filtri:
Specifica i campi disponibili per l'applicazione dei filtri e i valori validi per ciascuno di questi campi, in modo che l'agente comprenda i vincoli previsti per la creazione di filtri validi. Ad esempio, per filtrare i risultati per un datastore che contiene le informazioni del menu, potrebbe esserci un campo
mealcon valori validi "colazione", "pranzo" e "cena" e un camposervingSizeche può essere qualsiasi numero intero compreso tra 0 e 5. Le tue 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 l'agente è per un pubblico di utenti esterni, potrebbe essere necessario aggiungere istruzioni per impedire all'agente di rispondere potenzialmente 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."È utile anche fornire un esempio di questo caso.
Il parametro userMetadata fornisce informazioni sull'utente finale. Qualsiasi coppia chiave/valore può essere compilata in questo parametro. Questi metadati vengono trasmessi allo strumento per il datastore per migliorare i risultati di ricerca e la risposta dello strumento. È consigliabile fornire più esempi per indicare all'LLM dell'agente come compilare questo parametro.
Un esempio di valore parametro userMetadata per perfezionare i risultati di ricerca
pertinenti per uno specifico utente potrebbe essere:
"userMetadata": {
"favoriteColor": "blue",
...
}
Il parametro fallback fornisce una risposta con cui lo strumento del datastore deve rispondere
se non esiste una risposta riepilogativa valida per la query. È possibile fornire più esempi per indicare all'LLM dell'agente come completare il fallback per gli input dell'utente relativi a diversi argomenti. Inoltre, non ci saranno snippet
nell'output dello strumento. Questa ottimizzazione può essere usata
per ridurre la latenza e limitare l'uso dei token di input.
"fallback": "I'm sorry I cannot help you with that. Is there anything else I
can do for you?"
Se durante i test alcune risposte non soddisfano le tue aspettative, nella pagina Strumenti di uno strumento di datastore sono disponibili le seguenti personalizzazioni:
Fondamenta dell'affidabilità
Per ogni risposta generata dai contenuti dei datastore connessi, l'agente valuta un livello di confidenza, che misura l'affidabilità che tutte le informazioni nella risposta siano supportate da informazioni nei datastore. Puoi personalizzare le risposte da consentire selezionando il livello di confidenza più basso che ritieni adeguato. Verranno mostrate solo le risposte pari o superiori a quel livello di confidenza.
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 agente del datastore per la richiesta generativa di riassunto. Se non ne viene selezionata nessuna, viene usata l'opzione del modello predefinito. 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 riepilogo.
Il prompt è un modello di testo che può contenere segnaposto predefiniti. I segnaposto verranno sostituiti con i valori appropriati in fase di runtime e il testo finale verrà inviato all'LLM.
I segnaposto sono i seguenti:
$original-query: testo della query dell'utente.$rewritten-query: l'agente utilizza un modulo di riscrittura per riscrivere la query dell'utente originale in un formato più accurato.$sources: l'agente utilizza Enterprise Search per cercare 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 first 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 delle conversazioni 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. L'agente trasformerà questa costante in un messaggio facile da usare per l'utente.
Impostazioni payload
Le impostazioni del payload consentono di aggiungere gli snippet del datastore come contenuti avanzati nel payload della risposta che viene visualizzato in messenger.
Frasi escluse (configurazione a livello di agente)
Puoi scegliere di definire frasi specifiche che non dovrebbero essere consentite. Queste vengono configurate a livello di agente e utilizzate sia dagli LLM dell'agente che dagli strumenti del datastore. Se la risposta generata o parti del prompt LLM, ad esempio gli input dell'utente, contengono una qualsiasi delle frasi vietate testualmente, la risposta non verrà mostrata.
Strumenti per le funzioni
Se hai funzionalità accessibili dal codice client, ma non accessibili dagli strumenti OpenAPI, puoi utilizzare gli strumenti di funzione. Gli strumenti per le funzioni vengono sempre eseguiti sul lato client, non dall'app dell'agente.
La procedura è la seguente:
- Il codice client invia una richiesta di rilevamento di intent.
- L'app agente rileva che è necessario uno strumento per le funzioni e la risposta di rilevamento dell'intent contiene il nome dello strumento insieme agli argomenti di input. Questa sessione viene messa in pausa finché non viene ricevuta un'altra richiesta di rilevamento di intent con il risultato dello strumento.
- Il codice cliente chiama lo strumento.
- Il codice client invia un'altra richiesta di rilevamento di intent 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 di rilevamento iniziale di intent mediante 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 di intent, 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 per le funzioni, gli strumenti OpenAPI e datastore possono essere eseguiti sul lato client applicando un override dell'API durante l'interazione 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 intent che specifica l'esecuzione del client.
- L'app dell'agente rileva che è necessario uno strumento e la risposta di rilevamento dell'intent contiene il nome dello strumento insieme agli argomenti di input. Questa sessione viene messa in pausa finché non viene ricevuta un'altra richiesta di rilevamento di intent con il risultato dello strumento.
- Il codice cliente chiama lo strumento.
- Il codice client invia un'altra richiesta di rilevamento di intent che fornisce il risultato dello strumento come argomenti di output.