Strumenti

Utilizzando gli strumenti, puoi connettere le app degli agenti a sistemi esterni. Questi sistemi possono aumentare la conoscenza delle app degli agenti e migliorarle per eseguire in modo efficiente attività complesse.

Puoi usare gli strumenti integrati o creare strumenti personalizzati per soddisfare le tue esigenze.

Limitazioni

Si applicano le seguenti limitazioni:

  • Devi creare un datastore (o collegare un datastore esistente) quando si crea uno strumento di datastore per un'app agente.
  • App con entrambi datastore a blocchi e non a blocchi non sono supportati.

Strumenti integrati

Gli strumenti integrati sono ospitati da Google. Puoi attivare questi strumenti nelle app degli agenti senza bisogno di una configurazione manuale.

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.

L'app dell'agente è ottimizzata per determinare come e quando questi strumenti devono essere richiamati, ma puoi fornire altri esempi 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 viene 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 e header. Il tipo di parametro cookie non è ancora supportato.
  • I parametri definiti dallo schema OpenAPI supportano i seguenti tipi di dati: string, number, integer, boolean e array. Il tipo object non è 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

Durante le chiamate sono supportate le seguenti opzioni di autenticazione un'API esterna:

  • Autorizzazione agente di servizio Dialogflow
    • Dialogflow può generare un token ID. o il token di accesso utilizzando 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 risorsa, non hai bisogno di un'autorizzazione IAM aggiuntiva per chiamarli.
    • Un token di accesso può essere utilizzato per accedere ad altre API Google Cloud dopo aver concesso i ruoli richiesti service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
  • Chiave API
    • Puoi configurare l'autenticazione con chiave API specificando il nome della chiave, posizione 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. Necessità di ID client, client secret e endpoint token del provider OAuth da configurare in Dialogflow. Dialogflow scambia un token di accesso OAuth e lo passa nell'intestazione auth della richiesta.
    • Per altri flussi OAuth, devi usare lo strumento Funzioni per integrare con la tua interfaccia utente di accesso per scambiare il token.

  • Token di connessione

    • Puoi configurare l'autenticazione di connessione per passare dinamicamente il token di connessione dal cliente. Questo token è incluso nell'intestazione auth della richiesta.
    • Quando imposti l'autenticazione dello strumento, puoi specificare un parametro di sessione fungere 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

  • Certificato CA personalizzato

Accesso alla rete privata dello strumento OpenAPI

Lo strumento OpenAPI si integra con Accesso alla rete privata di Service Directory, in modo che possa connettersi ai target API all'interno della tua rete VPC. In questo modo il traffico all'interno della rete Google Cloud applica in modo forzato IAM Controlli di servizio VPC.

Per impostare uno strumento OpenAPI che ha come target una rete privata:

  1. Segui Configurazione della rete privata di Service Directory per configurare la rete VPC e l'endpoint di Service Directory.

  2. L'agente di servizio Dialogflow account di servizio con il seguente indirizzo deve esistere per il tuo progetto agente: 

    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.viewer del progetto Service Directory
    • servicedirectory.pscAuthorizedService del progetto di rete

  3. Fornire il servizio Service Directory insieme allo schema OpenAPI e informazioni di autenticazione facoltative durante la creazione dello strumento.

Strumenti per datastore

Gli strumenti del datastore possono essere utilizzati dall'app agente per trovare le risposte alle domande degli utenti finali archivi di dati. Puoi configurare un datastore di ogni tipo per strumento, e lo strumento eseguirà una query su ognuno di questi datastore per trovare le risposte. Per impostazione predefinita, l'app dell'agente chiamerà 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 possono contenere anche snippet relativi all'origine di contenuto utilizzato per generare la risposta. L'app dell'agente può fornire ulteriori istruzioni su come procedere con la risposta dai datastore o come rispondere in assenza di risposta.

Puoi sovrascrivere una risposta aggiungendo 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 connetterlo alla tua app, puoi usare 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 strumento per il datastore, il parametro di input dello strumento requestBody fornisce tre input facoltativi insieme alla stringa query richiesta: una stringa filter, un oggetto strutturato userMetadata e una stringa fallback.

Il parametro filter consente di filtrare le query di ricerca del tuo di dati strutturati o non strutturati con metadati. Questa stringa deve seguire le sintassi supportata delle espressioni di filtro per i datastore. Vari esempi ed esempi dettagliati sono incoraggiati a dare all'LLM agente istruzioni non viene compilato questo parametro. Nel caso di una stringa di filtro non valida, il filtro verranno ignorati quando esegui la query di ricerca.

Un esempio di stringa filter per perfezionare i risultati di ricerca in base alla posizione 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 ognuno di questi campi, in modo che l'agente comprenda i vincoli della creazione di filtri validi. Ad esempio, per filtrare i risultati per un datastore contenente le informazioni del menu, potrebbe esserci un campo meal con "colazione", "pranzo" e "cena" come valori validi; e un campo servingSize che 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 mantenere 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 Le coppie chiave/valore possono essere compilate in questo parametro. Questi metadati vengono passati nello strumento di datastore, per migliorare i risultati di ricerca e lo strumento. risposta. Si consiglia di fornire più esempi per indicare ai su come compilare questo parametro.

Esempio di valore parametro userMetadata per perfezionare i risultati di ricerca pertinenti per uno specifico utente potrebbero avere il seguente aspetto:

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

Il parametro fallback fornisce una risposta a cui lo strumento del datastore deve rispondere e se non esiste una risposta riepilogativa valida per la query. È possibile trovare più esempi per indicare all'LLM dell'agente come completare il fallback per l'utente input correlati a diversi argomenti. Inoltre, non ci saranno nell'output dello strumento. Questa ottimizzazione può essere usata 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 alcune risposte durante il test non soddisfano le tue aspettative, la seguenti personalizzazioni sono disponibili nella pagina Strumenti di uno strumento datastore:

Fondamenta dell'affidabilità

Per ogni risposta generata dai contenuti dei datastore connessi, l'agente valuta il livello di confidenza, che indica la confidenza nella risposta sono supportate dalle informazioni nei datastore. Puoi personalizzare quali risposte consentire selezionando quella più bassa il livello di sicurezza con cui ti senti a tuo agio. Solo risposte uguali o superiori a questo verrà visualizzato il 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 richiesta di riassunto generativo. Se non viene selezionato nessuno, viene utilizzato il 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 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 originale dell'utente in un formato più preciso.

  • $sources: l'agente 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 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 semplice per l'utente.

Impostazioni payload

Le impostazioni del payload consentono di aggiungere gli snippet del datastore come contenuti avanzati il payload della risposta che viene reso in messenger.

Frasi escluse (configurazione a livello di agente)

Puoi scegliere di definire frasi specifiche che non dovrebbero essere consentite. Queste impostazioni sono configurate a livello di agente e utilizzate sia dall'agente gli LLM e gli strumenti per i datastore. Se la risposta generata o parti dell'LLM come gli input dell'utente, contengono una qualsiasi delle frasi vietate parola, la risposta non verrà mostrata.

Strumenti per le funzioni

Se hai a disposizione una funzionalità accessibile tramite il codice cliente, ma non sono accessibili dagli strumenti OpenAPI, puoi usare 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:

  1. Il codice client invia una richiesta di rilevamento di intent.
  2. L'app agente rileva che è necessario uno strumento per le funzioni, e la risposta di rilevamento dell'intento contiene il nome dello strumento insieme agli argomenti di input. Questa sessione è in pausa finché non viene ricevuta un'altra richiesta di rilevamento di intent con il risultato dello strumento.
  3. Il codice cliente chiama lo strumento.
  4. 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 dell'intent iniziali usando 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, OpenAPI e gli strumenti per datastore può essere eseguito 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:

  1. Il codice cliente invia una richiesta di rilevamento di intent che specifica l'esecuzione del client.
  2. L'app dell'agente rileva che è necessario uno strumento, e la risposta di rilevamento dell'intento contiene il nome dello strumento insieme agli argomenti di input. Questa sessione è in pausa finché non viene ricevuta un'altra richiesta di rilevamento di intent con il risultato dello strumento.
  3. Il codice cliente chiama lo strumento.
  4. Il codice client invia un'altra richiesta di rilevamento di intent che fornisce il risultato dello strumento come argomenti di output.
Indietro
Interfaccia utente
Avanti
Best practice