Registrare e gestire gli agenti Dialogflow

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questa pagina descrive come registrare e utilizzare gli agenti Dialogflow con Gemini Enterprise.

Panoramica

Per utilizzare un agente Dialogflow con Gemini Enterprise, devi prima eseguirne il deployment e poi registrarlo. La registrazione dell'agente Dialogflow collega l'agente di cui è stato eseguito il deployment a Gemini Enterprise in modo che possano comunicare.

Prima di iniziare

Prima di registrare l'agente Dialogflow, devi assicurarti di aver completato questi passaggi:

• Esegui il deployment dell'agente Dialogflow. Per visualizzare la dashboard di Dialogflow e degli agenti di conversazione, consulta Agenti di conversazione.

• Il ruolo Gemini Enterprise Admin.

• Abilita l'API Discovery Engine. Per abilitare l'API Discovery Engine per il progetto Google Cloud, nella console Google Cloud , vai alla pagina API Discovery Engine.

  Vai all'API Discovery Engine

• Crea un'app Gemini Enterprise. Per saperne di più, consulta Crea un'app.

Registra un agente Dialogflow con Gemini Enterprise

Puoi registrare il tuo agente Dialogflow con Gemini Enterprise utilizzando la consoleGoogle Cloud o l'API REST. La registrazione rende l'agente disponibile per gli utenti all'interno di un'app Gemini Enterprise.

Quota di registrazione e licenze degli agenti: la registrazione di un agente con un'app consuma un'unità della quota di creazione giornaliera degli agenti in pool del tuo progetto (discoveryengine.googleapis.com/agents_tier_enterprise_regional). La quota è determinata dal numero di licenze Gemini Enterprise Standard (1 creazione per utente al giorno, in pool) o Plus (10 per utente al giorno, in pool) distribuite al progetto. Le licenze Frontline forniscono una quota di creazione pari a 0.

Se registri un agente di backend in più app o motori Gemini Enterprise nello stesso progetto, ogni chiamata API di registrazione (agents.create) viene conteggiata come creazione di un agente rispetto a questa quota giornaliera. Gli script di deployment automatico o le pipeline CI/CD che registrano un agente in molte app possono riscontrare l'errore HTTP 429 RESOURCE_EXHAUSTED: Agent creation quota exceeded se il numero di chiamate di registrazione in un giorno supera il numero di licenze Standard distribuite. Assicurati che al tuo progetto siano state assegnate licenze Standard sufficienti prima di eseguire implementazioni di più app. Per maggiori dettagli, consulta Quote di creazione giornaliere.

Console

Per registrare un agente Dialogflow utilizzando la console Google Cloud , segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

   Vai a Gemini Enterprise

2. Seleziona il progetto.

3. Fai clic sul nome dell'app con cui vuoi registrare l'agente.

4. Fai clic su Agenti > Aggiungi agenti. Viene visualizzato il riquadro Scegli un tipo di agente.

5. Nella scheda Agente personalizzato tramite Dialogflow, fai clic su Aggiungi per registrare il tuo agente Dialogflow con Gemini Enterprise. Viene visualizzato il riquadro Configurazione.

6. Per configurare l'agente, segui questi passaggi:

   1. Inserisci un nome nel campo Nome dell'agente. Questo valore viene visualizzato in Gemini Enterprise come nome visualizzato dell'agente.

   2. Inserisci una descrizione nel campo Descrivi il tuo agente. Questo valore viene utilizzato da un LLM per determinare se richiamare l'agente in risposta a una query dell'utente.

   3. Inserisci il percorso della risorsa dell'agente Dialogflow che vuoi registrare con Gemini Enterprise nel campo Origine agente Dialogflow.

      Utilizza questo formato: projects/{project}/locations/{location}/agents/{agent}

      L'opzione Disponibilità agente, Se selezionata, è impostata per impostazione predefinita.

   4. Fai clic su Crea.

curl

Questo esempio di codice mostra come registrare l'agente:

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "icon": {
        "uri": "ICON_URI"
      },
      "dialogflowAgentDefinition": {
        "dialogflowAgent": "projects/DIALOGFLOW_PROJECT_ID/locations/DIALOGFLOW_LOCATION/agents/DIALOGFLOW_AGENT_ID"
      }
    }'

Sostituisci le variabili con i valori:

• PROJECT_ID: l'ID del tuo progetto Google Cloud .
• APP_ID: l'ID della tua app Gemini Enterprise.
• DISPLAY_NAME: il nome facile da usare per l'agente che viene visualizzato in Gemini Enterprise.
• DESCRIPTION: una breve spiegazione di ciò che fa l'agente, visibile agli utenti in Gemini Enterprise. Ad esempio, Estrai le informazioni chiave dalle fatture caricate per i viaggi di lavoro.
• ICON_URI: l'URI pubblico di un'icona visualizzata accanto al nome dell'agente Dialogflow. Puoi anche fornire un'immagine con codifica Base64 in icon.content.
• DIALOGFLOW_PROJECT_ID: l'ID progetto Google Cloud che identifica la località dell'agente Dialogflow.
• DIALOGFLOW_LOCATION: la posizione geografica specifica in cui è ospitato l'agente Dialogflow, ad esempio global o us-central1.
• DIALOGFLOW_AGENT_ID: l'identificatore univoco del tuo agente Dialogflow.

La risposta corretta a questo comando restituisce tutti i campi della risorsa agente Dialogflow appena creata, incluso il nome univoco della risorsa nel campo name. Questo nome della risorsa può essere utilizzato per aggiornamenti o riferimenti futuri.

Elenca gli agenti connessi a un'app

Il seguente esempio di codice mostra come ottenere i dettagli di tutti gli agenti connessi alla tua app:

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

Sostituisci le variabili con i valori:

• ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
  • us per la multi-regione Stati Uniti
  • eu per la multi-regione UE
  • global per la località globale
  Per saperne di più, consulta Specifica una multi-regione per il datastore.
• PROJECT_ID: l'ID del tuo progetto Google Cloud .
• LOCATION: la località multiregionale della tua app: global, us o eu.
• APP_ID: l'ID della tua app Gemini Enterprise.

Se l'agente non è predefinito da Google, la risposta include un campo name nelle prime righe. Il valore di questo campo contiene l'ID agente alla fine del percorso. Ad esempio, nella seguente risposta, l'ID agente è 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

Visualizza i dettagli di un agente Dialogflow

Il seguente esempio di codice mostra come recuperare i dettagli di un agente registrato con Gemini Enterprise:

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Sostituisci le variabili con i valori:

• ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
  • us per la multi-regione Stati Uniti
  • eu per la multi-regione UE
  • global per la località globale
  Per saperne di più, consulta Specifica una multi-regione per il datastore.
• PROJECT_ID: l'ID del tuo progetto Google Cloud .
• LOCATION: la località multiregionale della tua app: global, us o eu.
• APP_ID: l'ID della tua app Gemini Enterprise.
• AGENT_ID: l'ID dell'agente. Puoi trovare l'ID agente elencando gli agenti collegati alla tua app.

Aggiorna un agente Dialogflow

Tutti i campi forniti durante la registrazione dell'agente possono essere aggiornati. I seguenti campi sono obbligatori durante la procedura di aggiornamento:

• displayName
• description
• reasoning_engine

Quando aggiorni un campo, tutti i campi e i relativi valori devono essere ridefiniti nella richiesta di aggiornamento, anche se non vengono apportate modifiche a un campo specifico.

Questo esempio di codice mostra come aggiornare la registrazione dell'agente Dialogflow:

curl

  curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
  "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "icon": {
        "uri": "ICON_URI"
      },
      "dialogflowAgentDefinition": {
        "dialogflowAgent": "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/agents/DIALOGFLOW_AGENT_ID"
      }
    }'

Sostituisci le variabili con i valori:

• PROJECT_ID: l'ID del tuo progetto Google Cloud .
• AGENT_RESOURCE_NAME: il nome della risorsa della registrazione dell'agente da aggiornare.
• DISPLAY_NAME:il nome visualizzato dell'agente.
• DESCRIPTION: la descrizione dell'agente visualizzata in Gemini Enterprise. La descrizione è solo a vantaggio dell'utente.
• ICON_URI: l'URI pubblico di un'icona visualizzata accanto al nome dell'agente Dialogflow. Puoi anche fornire un'immagine con codifica Base64 in icon.content.
• REASONING_ENGINE_LOCATION: la località cloud del motore di ragionamento in cui stai creando un agente.
• DIALOGFLOW_AGENT_ID: l'identificatore univoco del tuo agente Dialogflow.

Elimina un agente Dialogflow

Il seguente esempio di codice mostra come eliminare un agente connesso alla tua app:

REST

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Sostituisci le variabili con i valori:

• ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
  • us per la multi-regione Stati Uniti
  • eu per la multi-regione UE
  • global per la località globale
  Per saperne di più, consulta Specifica una multi-regione per il datastore.
• PROJECT_ID: l'ID del tuo progetto Google Cloud .
• LOCATION: la località multiregionale della tua app: global, us o eu
• APP_ID: l'ID della tua app Gemini Enterprise.
• AGENT_ID: l'ID dell'agente. Puoi trovare l'ID agente elencando gli agenti collegati alla tua app.

Esempio di comando e risultato

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890/operations/delete-agent-12345678901234567890",
  "done": true
}