Strumenti

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, 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, 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 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.
  • Autenticazione TLS reciproca
  • Certificato CA personalizzato

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. Ti consigliamo di avere diversi esempi 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\")"

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
    
  • $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:

  1. Il codice client invia una richiesta di rilevamento dell'intent.
  2. 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.
  3. Il codice cliente chiama lo strumento.
  4. 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:

  1. Il codice client invia una richiesta di rilevamento dell'intent che specifica l'esecuzione del client.
  2. 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.
  3. Il codice cliente chiama lo strumento.
  4. Il codice client invia un'altra richiesta di rilevamento dell'intent che fornisce i risultati dello strumento come argomenti di output.