Guida rapida

Questa guida fornisce una guida rapida end-to-end per la configurazione di Omnichannel Gateway. Scoprirai come configurare un agente Agent Studio come destinazione, configurare un canale WebChat come origine e creare una policy di routing per collegarli.

Prima di iniziare

Prima di iniziare questa guida rapida, devi avere un Google Cloud progetto e completare i passaggi di configurazione iniziali:

  1. Abilita API e agente di servizio: assicurati di aver abilitato le API necessarie e configurato l'agente di servizio come descritto nella panoramica delle istruzioni.
  2. Configura un agente Agent Studio: crea e configura un agente Agent Studio e crea un profilo di conversazione per l'agente. Per istruzioni dettagliate, consulta la documentazione relativa agli agenti conversazionali e Crea un profilo di conversazione per un agente CX Agent Studio. L'agente deve essere creato in una regione supportata da Omnichannel Gateway.
  3. Prepara un'applicazione web per i test: ti serve un sito web o un'applicazione web su cui eseguire il deployment del widget di chat web per i test. Può trattarsi di qualsiasi pagina web di origine sicura, incluso un server di sviluppo web locale (ad esempio l'avvio di un server locale con python -m http.server) o un servizio di cui è stato eseguito il deployment su Cloud Run o simili.

Passaggio 1: configura l'agente Agent Studio (destinazione)

Per collegare l'agente Agent Studio a Omnichannel Gateway, devi configurare un account di servizio per l'esecuzione dell'agente e creare una configurazione dell'endpoint di destinazione.

Configura il account di servizio per l'esecuzione dell'agente

Tutti gli agenti vengono eseguiti con un account di servizio. Quando Omnichannel Gateway effettua chiamate per conto dell'agente, utilizza questo account di servizio per l'autenticazione. Puoi utilizzare questo account di servizio per limitare l'ambito di accesso per l'agente.

Crea un account di servizio per l'esecuzione dell'agente. Assegna i seguenti ruoli:

  • roles/serviceusage.serviceUsageConsumer
  • Qualsiasi altro ruolo richiesto dall'agente.

Inoltre, concedi all'agente di servizio Omnichannel Gateway il ruolo Utente account di servizio (roles/iam.serviceAccountUser) nell'account di servizio per l'esecuzione dell'agente per consentirgli di eseguire i flussi di lavoro come account di servizio:

gcloud

gcloud iam service-accounts create agent-runner \
    --description="Service account for executing agentic application workflows" \
    --display-name="Agent Runner" \
    --project="PROJECT_ID"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:agent-runner@PROJECT_ID." \
    --role="roles/serviceusage.serviceUsageConsumer"

gcloud iam service-accounts add-iam-policy-binding \
    agent-runner@PROJECT_ID. \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-agenticapplications." \
    --role="roles/iam.serviceAccountUser" \
    --project="PROJECT_ID"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:agent-runner@PROJECT_ID." \
    --role="roles/dialogflow.serviceAgent"

Se l'agente richiede funzionalità di chiamata di strumenti aggiuntive, puoi aggiungere autorizzazioni più specifiche in un secondo momento.

Crea la configurazione dell'endpoint di destinazione

Crea una configurazione dell'endpoint di destinazione che rimandi al profilo di conversazione di Agent Studio.

Per collegare l'agente a Omnichannel Gateway, crea una configurazione dell'endpoint eseguendo i comandi di esempio riportati di seguito. Sostituisci i segnaposto con il progetto di destinazione, l'ID agente e i dettagli del account di servizio:

curl

curl -i -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://agenticapplications.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/omnichannelEndpointConfigs" \
  -d @- <<EOF

{
    "displayName": "Agent Studio Destination Configuration",
    "destinationConfig": {
      "conversationProfile": {
        "conversationProfile": "projects/PROJECT_ID/locations/LOCATION/conversationProfiles/CONVERSATION_PROFILE_ID",
        "serviceAccount": "projects/PROJECT_ID/serviceAccounts/agent-runner@PROJECT_ID."
      }
    }
}

EOF

Passaggio 2: configura il canale WebChat (origine)

Per ricevere i messaggi in arrivo dagli utenti, configura un canale WebChat come endpoint di origine, configura un broker di token per l'autenticazione sicura e incorpora il widget di chat nel tuo sito web.

Crea la configurazione dell'endpoint di origine

Crea una configurazione dell'endpoint di origine per WebChat.

Per collegare l'agente a Omnichannel Gateway, crea una configurazione dell'endpoint eseguendo i comandi di esempio riportati di seguito. Sostituisci i segnaposto con il progetto di destinazione, l'ID agente e i dettagli del account di servizio:

curl

curl -i -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://agenticapplications.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/omnichannelEndpointConfigs" \
  -d @- <<EOF

{
  "displayName": "WebChat Source Configuration",
  "sourceConfig": {
    "webChatSdkConfig": {}
  }
}

EOF

Configura il broker di token

Omnichannel Gateway richiede richieste autenticate che utilizzano token di autenticazione per utilizzare WebChat. La risorsa del broker di token genera token di accesso che il widget lato client utilizza per chiamare le API di Google.

Crea un account di servizio per il broker di token

Crea un account di servizio specifico per il broker di token. Assegna i seguenti ruoli:

  • roles/agenticapplications.user

Di seguito è riportato un insieme di comandi di esempio per eseguire questa operazione in gcloud:

gcloud

gcloud iam service-accounts create token-broker \
    --description="Service account for the token broker application" \
    --display-name="Service account for Token Broker" \
    --project="PROJECT_ID"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:token-broker@PROJECT_ID." \
    --role="roles/agenticapplications.user"

Crea la risorsa del broker di token

Esegui il seguente comando cURL per inizializzare il broker. Non dimenticare di sostituire le variabili in base alle esigenze:

curl

curl -i -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://agenticapplications.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/omnichannelTokenBrokers" \
  -d @- <<EOF
{
  "displayName": "A broker",
  "issuerServiceAccount": "YOUR_BROKER_SERVICE_ACCOUNT_HERE"
}
EOF

Incorpora e inizializza il widget di chat

Incorpora e inizializza il widget di chat web sul tuo sito web seguendo le istruzioni riportate in Incorporare il widget nel sito web.

Configura l'elemento chat-messenger nella pagina HTML per connetterti alla configurazione dell'endpoint di origine. Sostituisci l'ID progetto, la località e i dettagli della configurazione dell'endpoint con i tuoi:

<chat-messenger
  project-id="PROJECT_ID"
  enable-audio-input="false"
  location="LOCATION"
  service='{"name":"omnichannel", "endpointConfig": "projects/PROJECT_ID/locations/LOCATION/omnichannelEndpointConfigs/SOURCE_ENDPOINT_CONFIG_ID"}'
  language-code="en"
  url-allowlist="https://gstatic.com/"
></chat-messenger>

Poi, utilizza chatSdk e il nome della risorsa del broker di token per stabilire un'autenticazione sicura:

<script>
  window.addEventListener("chat-messenger-loaded", async () => {
    const context = await window.chatSdk.prebuilts.concorde.createContext({
      tokenBroker: {
        tokenBrokerName: "projects/PROJECT_ID/locations/LOCATION/omnichannelTokenBrokers/TOKEN_BROKER_NAME",
      },
    });
    window.chatSdk.registerContext(context);
  });
</script>

Passaggio 3: configura una route

Per connettere il traffico conversazionale in entrata dal canale di origine WebChat all'agente di destinazione Agent Studio, devi creare una route. Questo esempio utilizza una policy di routing statica.

Per creare la route, esegui il seguente comando di esempio. Sostituisci i segnaposto con il progetto di destinazione e i dettagli della configurazione dell'endpoint:

curl

curl -i -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://agenticapplications.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/omnichannelRoutes" \
  -d @- <<EOF

{
  "displayName": "WebChat to Agent Studio Route",
  "sourceEndpointConfig": [
    "projects/PROJECT_ID/locations/LOCATION/omnichannelEndpointConfigs/SOURCE_ENDPOINT_CONFIG_ID"
  ],
  "staticRoutingPolicy": {
    "destinationEndpointConfigs": [
      "projects/PROJECT_ID/locations/LOCATION/omnichannelEndpointConfigs/DESTINATION_ENDPOINT_CONFIG_ID"
    ],
    "deadline": "10s"
  }
}

EOF

Passaggio 4: testa l'integrazione

Una volta configurati l'agente, il canale e la route, puoi testare il flusso conversazionale end-to-end:

  1. Apri l'applicazione web contenente il widget di chat incorporato. Se stai eseguendo test in locale, puoi avviare un server web locale nella directory del file HTML eseguendo python -m http.server nel terminale e accedendo a http://localhost:8000 nel browser.
  2. Fai clic sul widget di chat per aprire la finestra di conversazione.
  3. Invia un messaggio e verifica di ricevere una risposta dall'agente Agent Studio instradato tramite Omnichannel Gateway.

Passaggi successivi