Tramite gli strumenti, puoi connettere le app dell'agente a sistemi esterni. Questi sistemi possono ampliare la conoscenza delle app degli agenti e consentire loro di eseguire attività complesse in modo efficiente.
Puoi utilizzare strumenti integrati o creare strumenti personalizzati in base alle tue esigenze.
Limitazioni
Si applicano le seguenti limitazioni:
- Quando crei uno strumento del datastore per un'app dell'agente, devi creare un datastore (o connettere un datastore esistente).
- Le app con datastore in blocchi e non in blocchi non sono supportate.
Strumenti integrati
Gli strumenti integrati sono ospitati da Google. Puoi attivare questi strumenti nelle app degli agenti senza doverli configurare manualmente.
Gli strumenti integrati supportati sono:
Code Interpreter: uno strumento proprietario di Google che combina la capacità di generazione ed esecuzione di codice e consente all'utente di eseguire varie attività, tra cui: analisi dei dati, visualizzazione dei dati, elaborazione di testi, risoluzione di equazioni o problemi di ottimizzazione.
L'app dell'agente è ottimizzata per determinare come e quando richiamare questi strumenti, ma puoi fornire esempi aggiuntivi per soddisfare i 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 chiama 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 devono essere vuoti o 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.
- È possibile 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 risorse, non sono necessarie ulteriori autorizzazioni IAM 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 della chiave API specificando il nome della chiave, il percorso della richiesta (stringa di intestazione o di query) e la chiave API in modo che Dialogflow passi la chiave API nella richiesta.
- OAuth
- Il flusso delle credenziali client OAuth è supportato per l'autenticazione server-server. In Dialogflow è necessario configurare ID client, client secret ed endpoint token del provider OAuth. Dialogflow scambia un token di accesso OAuth e lo passa nell'intestazione auth della richiesta.
- Per altri flussi OAuth, devi utilizzare lo strumento per le funzioni per l'integrazione con la tua UI di accesso per scambiare il token.
Token di connessione
- Puoi configurare l'autenticazione di connessione in modo da passare dinamicamente il token di connessione dal client. Questo token è incluso nell'intestazione di autenticazione della richiesta.
- Quando configuri l'autenticazione dello strumento, puoi designare un parametro di sessione
che agisca 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 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, in modo da potersi connettere alle destinazioni API all'interno della tua rete VPC. In questo modo il traffico all'interno della rete Google Cloud viene mantenuto e vengono applicati IAM e Controlli di servizio VPC.
Per impostare uno strumento OpenAPI che abbia come target una rete privata:
Consulta la pagina relativa alla configurazione della rete privata di Service Directory per configurare la tua rete VPC e l'endpoint di Service Directory.
Per il progetto 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 del datastore
Gli strumenti del datastore possono essere utilizzati da un'app di agente per rispondere alle domande dell'utente finale dai datastore. Puoi configurare un datastore per ogni tipo per strumento e lo strumento eseguirà una query su ciascuno di questi datastore per trovare le risposte. Per impostazione predefinita, l'app dell'agente chiama lo strumento del datastore per tuo conto. In alternativa, puoi eseguire gli strumenti per il datastore sul lato client.
Il tipo di datastore può essere uno dei seguenti:
PUBLIC_WEB: un datastore che include contenuti web pubblici.UNSTRUCTURED: un datastore che contiene dati privati non strutturati.STRUCTURED: un datastore che contiene dati strutturati (ad esempio, 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 di datastore potrebbero anche contenere snippet sull'origine di contenuto utilizzata per generare la risposta. L'app 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 di Domande frequenti per una domanda specifica.
È possibile usare degli esempi per migliorare ulteriormente il comportamento dell'app 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 menu di navigazione a sinistra della console. Segui le istruzioni per creare un datastore.
Parametri di ricerca aggiuntivi
Durante la creazione di esempi di strumenti per il datastore, sono disponibili due parametri facoltativi, insieme alla stringa query obbligatoria: una stringa filter e un oggetto strutturato userMetadata.
Il parametro filter consente di filtrare le query di ricerca dei dati strutturati o dei dati non strutturati con i metadati. Questa stringa deve seguire la sintassi delle espressioni di filtro supportata per i datastore.
Ti consigliamo di avere più esempi ed esempi dettagliati per indicare all'LLM dell'agente come compilare questo parametro. Nel caso di una 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 avere il seguente aspetto:
"filter": "country: ANY(\"Canada\")"
Best practice per l'applicazione di filtri:
Specifica i campi disponibili per l'applicazione di filtri e i valori validi di ciascuno di questi campi, in modo che l'agente comprenda i vincoli relativi alla creazione di filtri validi. Ad esempio, per filtrare i risultati per un datastore contenente informazioni su un menu, potrebbero esserci un campo
mealcon "colazione", "pranzo" e "cena" come valori validi; e un camposervingSizeche può contenere qualsiasi numero intero compreso tra 0 e 5. Le istruzioni possono 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 segmento di pubblico di utenti esterno, potrebbe essere necessario aggiungere istruzioni per evitare che l'agente risponda 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. In questo parametro è possibile compilare qualsiasi coppia chiave-valore. Questi metadati vengono passati nello strumento del datastore per fornire informazioni più utili ai risultati di ricerca e alla risposta dello strumento. Ti consigliamo di 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 un utente specifico potrebbe avere il seguente aspetto:
"userMetadata": {
"favoriteColor": "blue",
...
}
Se durante il test noti che alcune risposte non soddisfano le tue aspettative, nella pagina dello strumento di uno strumento di datastore sono disponibili le seguenti personalizzazioni:
Fiducia di base
Per ogni risposta generata dai contenuti dei tuoi datastore connessi, l'agente valuta un livello di confidenza, che valuta il livello di sicurezza che tutte le informazioni nella risposta sono supportate da informazioni nei datastore. Puoi personalizzare le risposte da consentire selezionando il livello di affidabilità più basso che ritieni adeguato. Verranno mostrate solo le risposte al 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 agente di datastore per la richiesta generativa di riassunto. Se non viene selezionato alcun modello, viene utilizzata un'opzione di modello predefinito. La tabella seguente contiene le opzioni disponibili:
| Identificatore modello | Supporto delle lingue |
|---|---|
| text-bison@001 | Funzionalità disponibile in tutte le lingue supportate. |
| text-bison@002 | Funzionalità disponibile in tutte le lingue supportate. |
| text-bison@001 ottimizzato (conversazionale) | Al momento è supportato solo l'inglese. |
| text-bison@001 ottimizzato (informativo) | Al momento è supportato solo l'inglese. |
| gemelli pro | Funzionalità disponibile in tutte le lingue supportate. |
Puoi anche fornire il tuo prompt per la chiamata LLM di riassunto.
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 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 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 dovrebbe indicare all'LLM di restituire "NOT_ENOUGH_INFORMATION" quando non può fornire una risposta. L'agente trasformerà questa costante in un messaggio intuitivo per l'utente.
Frasi escluse (configurazione a livello di agente)
Puoi scegliere di definire frasi specifiche che non devono essere consentite. Questi parametri sono configurati a livello di agente e vengono utilizzati sia dagli strumenti LLM dell'agente sia dagli strumenti del datastore. Se la risposta generata o parti della richiesta LLM, ad esempio gli input dell'utente, contengono parola per parola una delle frasi vietate, la risposta non verrà mostrata.
Strumenti per le funzioni
Se le funzionalità sono accessibili tramite il codice client, ma non agli strumenti OpenAPI, puoi utilizzare gli strumenti per le funzioni. 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 dell'intent.
- L'app agente rileva che è necessario uno strumento di funzione e la risposta di rilevamento dell'intent 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'intento con il risultato dello strumento.
- Il codice cliente chiama lo strumento.
- Il codice client invia un'altra richiesta di rilevamento dell'intent che fornisce i risultati dello strumento come argomenti di output.
L'esempio seguente mostra lo schema di input e di output di uno strumento funzionale:
{
"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 dell'intent 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'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, OpenAPI e gli strumenti di 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 dell'intent che specifica l'esecuzione del client.
- L'app 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 fino a quando non viene ricevuta un'altra richiesta di rilevamento dell'intento con il risultato dello strumento.
- Il codice cliente chiama lo strumento.
- Il codice client invia un'altra richiesta di rilevamento dell'intent che fornisce i risultati dello strumento come argomenti di output.