Trasferire le conversazioni a ServiceNow

Collega Virtual Agent di ServiceNow a un agente di Copilot Studio e configura l'instradamento a un agente umano in ServiceNow. L'integrazione utilizza una Funzione di Azure per inoltrare le attività di Direct Line e un trasformatore personalizzato di ServiceNow per rilevare gli eventi di handoff.

Panoramica

L'integrazione tra Copilot Studio e ServiceNow richiede i passaggi di configurazione generali seguenti:

1. Distribuisci una funzione Azure come proxy per Direct Line.

2. Configurare Bot Interconnect in ServiceNow.

3. Collegare gli argomenti tra ServiceNow Virtual Agent e Copilot Studio.

4. Estendi DirectLinePrimaryBotIntegrationInboundTransformer.

5. Configurare l'handoff in Copilot Studio.

Prerequisites

Prima di iniziare, assicurarsi di avere i prerequisiti seguenti:

• Un account ServiceNow attivo con ServiceNow Virtual Agent e ServiceNow Bot Interconnect attivati. Ti serve ServiceNow Yokohama o versione successiva.
• Un agente Copilot Studio configurato senza autenticazione. Questa impostazione si applica all'accesso dell'utente finale; il relay server-to-server utilizza un Direct Line secret per autorizzare l'accesso al canale.
• Accesso amministratore a ServiceNow.

Crea una funzione Azure come relè verso Direct Line

La funzione Azure agisce come un relay così che ServiceNow Bot Interconnect possa recuperare attività, come messaggi ed eventi, da una conversazione in corso con un agente di Copilot Studio.

Richiesta di esempio inviata da ServiceNow Bot Interconnect

GET /api/relayToDirectLine HTTP/1.1
Host: your-function-app.azurewebsites.net
Authorization: Bearer YOUR_DIRECT_LINE_SECRET_HERE
ConversationId: abc123def456-conversation-id
Watermark: 5
WaitTime: 3000

Risposta di esempio dalla funzione di Azure

{
    "activities": [
        {
            "type": "message",
            "id": "0000001",
            "timestamp": "2025-07-13T13:46:43.6095506Z",
            "text": "Hello, I'm a Copilot Studio Agent.",
            "from": {
                "id": "bot-id",
                "name": "Copilot Studio Agent",
                "role": "bot"
            },
            "conversation": {
                "id": "wwjmISGzmd3FzMEAgotiJ-us"
            }
        },
        {
            "type": "message",
            "id": "0000002",
            "timestamp": "2025-07-13T13:46:45.0000000Z",
            "text": "speak to a live agent",
            "from": {
                "id": "user-id",
                "name": "User",
                "role": "user"
            },
            "conversation": {
                "id": "wwjmISGzmd3FzMEAgotiJ-us"
            }
        },
        {
            "type": "event",
            "id": "0000006",
            "timestamp": "2025-07-13T13:46:51.2854808Z",
            "name": "handoff.initiate",
            "value": {
                "va_LastPhrase": "speak to a live agent",
                "va_Topics": ["Escalate"]
            }
        }
    ],
    "watermark": "10"
}

Creare e distribuire la funzione

È possibile creare e distribuire la funzione di Azure v3 descritta nella documentazione di ServiceNow o nella funzione di Azure v4 disponibile nel repository GitHub di Copilot Studio.

Opzione 1: Distribuire la funzione di Azure v3

Per creare e distribuire la funzione di Azure v3, seguire la procedura descritta nella documentazione di ServiceNow:

1. Crea una funzione JavaScript in Microsoft Azure utilizzando Visual Studio Code.

2. Distribuire la funzione in Azure e recuperare l'URL della funzione da usare in ServiceNow Bot Interconnect.

Opzione 2: Distribuire la funzione di Azure v4

In alternativa, è possibile usare la funzione di Azure v4 disponibile nel repository GitHub di Copilot Studio:

1. Clona il repository Copilot Studio Samples. Apri il progetto fornito in contact-center/servicenow/DirectLineAzureFunction Visual Studio Code.

2. Segui le istruzioni di configurazione del progetto. Crea un'app di funzioni in Azure e distribuisci il progetto di relay fornito. Non sostituire il relay con una nuova funzione HTTP generata dal template. Ulteriori informazioni in Distribuire file di progetto.

3. Dopo il deployment, copiare l'URL della funzione HTTP del relay per l'uso in ServiceNow Bot Interconnect. Usa l'endpoint della funzione, non l'URL di base della Function App. Scopri di più in Ottieni l'URL di una funzione attivata HTTP in Azure.

Configurare l'interfaccia bot in ServiceNow

1. Ottieni il segreto Direct Line del tuo agente.

2. Aggiungere la chiave segreta Direct Line alla tua istanza di Virtual Agent Bot Interconnect.

Mappare gli argomenti tra ServiceNow Virtual Agent e Copilot Studio

1. Crea un argomento contenitore di Virtual Agent Bot Interconnect per chiamare argomenti di Copilot Studio.

Estensione di DirectLinePrimaryBotIntegrationInboundTransformer

Il componente DirectLinePrimaryBotIntegrationInboundTransformer integrato non esegue il parsing dell'evento di Copilot Studio handoff.initiate quando la conversazione deve essere trasferita a un agente live.

La shouldConnectToAgent funzione in DirectLinePrimaryBotIntegrationInboundTransformer restituisce sempre false:

shouldConnectToAgent: function(response) {
    return false;
}

Per gestire correttamente gli eventi di handoff, creare un trasformatore personalizzato che estende il trasformatore predefinito e rileva l'evento handoff.initiate .

shouldConnectToAgent: function() {
        var response = this._response || {};
        var activities = response.activities || [];

        var handoffDetected = activities.some(function(activity) {
            return activity.type === "event" && activity.name === "handoff.initiate";
        });

        if (handoffDetected) {
            return true;
        }
        return false;
    }

Creare il trasformatore personalizzato

1. In ServiceNow passare all'ambito dell'applicazione Bot Interconnect .

   1. Selezionare l'icona del globo nell'angolo in alto a destra.

   2. Selezionare Bot Interconnect nell'elenco delle applicazioni.

2. Creare un nuovo script Include.

   1. Passare a System Definition>Script Includes.

   2. Seleziona Nuovo.

   3. Configura le impostazioni seguenti:

   • Nome: CustomDirectLineInboundTransformer
   • Nome API: sn_va_bot_ic.CustomDirectLineInboundTransformer (generato automaticamente)
   • Applicazione: Bot Interconnect (autoselezionata)
   • Accessibile da: solo questo ambito dell'applicazione
   • Attivo: Selezionato

3. Sostituire il contenuto dello script predefinito con il codice trasformatore personalizzato dal repository di esempi di Copilot Studio.

4. Selezionare Invia per salvare l'opzione Includi script.

Aggiornare la configurazione di Bot Interconnect

1. Passare a Workflow Studio.

   1. In ServiceNow, accedere a Workflow Studio.

   2. In Actions (Azioni) trovare Direct Line Primary Bot Integration Inbound Transformer (Trasformatore in ingresso per l'integrazione del bot primario Direct Line).

2. Modificare l'azione del trasformatore.

   1. Apri l'azione Direct Line Primary Bot Integration Inbound Transformer.

   2. Nell'editor di script, metti in commento il trasformatore predefinito e sostituiscilo con una chiamata al trasformatore personalizzato.

   (function execute(inputs, outputs) {
      var clientVariables = JSON.parse(inputs['client_variables']);
      var response = JSON.parse(inputs['response']);
      //set client variables
      response.clientVariables = clientVariables;
   
      //var transformedResponse = new sn_va_bot_ic.DirectLinePrimaryBotIntegrationInboundTransformer(response).transformResponse();
      var transformedResponse = new sn_va_bot_ic.CustomDirectLineInboundTransformer(response).transformResponse();
   
      outputs['transformed_response'] = transformedResponse;
    })(inputs, outputs);
   

3. Salvare le modifiche apportate all'azione e pubblicare.

Configurazione del passaggio

Per configurare il handoff a un agente umano in ServiceNow, aggiungi un nodo Trasferisci la conversazione al tema Escalate del tuo agente.

1. In Copilot Studio, apri il tuo agente e vai a Topics>System>Escalate.

2. Selezionare + (Aggiungi nodo) >Gestione argomenti>Trasferimento conversazione.

3. Salva l'argomento e pubblica l'agente.

Il nodo Trasferisci conversazione invia un handoff.initiate evento che il trasformatore personalizzato di ServiceNow rileva ed elabora.

Esempio di escalation dell'argomento YAML

È anche possibile importare la configurazione YAML seguente per un argomento di escalation completo con funzionalità di trasferimento:

kind: AdaptiveDialog
startBehavior: CancelOtherTopics
beginDialog:
  kind: OnEscalate
  id: main
  intent:
    displayName: Escalate
    includeInOnSelectIntent: false
    triggerQueries:
      - Talk to agent
      - Talk to a person
      - Talk to someone
      - Call back
      - Call customer service
      - Call me please
      - Call support
      - Call technical support
      - Can an agent call me
      - Can I call
      - Can I get in touch with someone else
      - Can I get real agent support
      - Can I get transferred to a person to call
      - Can I have a call in number Or can I be called
      - Can I have a representative call me
      - Can I schedule a call
      - Can I speak to a representative
      - Can I talk to a human
      - Can I talk to a human assistant
      - Can someone call me
      - Chat with a human
      - Chat with a representative
      - Chat with agent
      - Chat with someone please
      - Connect me to a live agent
      - Connect me to a person
      - Could some one contact me by phone
      - Customer agent
      - Customer representative
      - Customer service
      - I need a manager to contact me
      - I need customer service
      - I need help from a person
      - I need to speak with a live agent
      - I need to talk to a specialist please
      - I want to talk to customer service
      - I want to proceed with live support
      - I want to speak with a consultant
      - I want to speak with a live tech
      - I would like to speak with an associate
      - I would like to talk to a technician
      - Talk with tech support member

  actions:
    - kind: TransferConversationV2
      id: transferConversationV2_3JXrI7
      transferType:
        kind: TransferToAgent
        messageToAgent:
        context:
          kind: AutomaticTransferContext

Troubleshooting

Se si verificano errori nel widget di chat dell'agente virtuale ServiceNow, seguire questa procedura di risoluzione dei problemi:

Controllare i log delle funzioni di Azure

1. Verificare che l'Azure Function funzioni correttamente e che non restituisca errori.

2. Visualizzare i log in tempo reale usando i log di streaming di Funzioni di Azure.

3. Per informazioni dettagliate sui dati di telemetria e sugli errori, vedere Application Insights.

Attiva il debug ServiceNow

Usare gli strumenti di debug predefiniti di ServiceNow per tracciare il flusso di esecuzione:

1. Attiva Script Tracer in ServiceNow.

2. Ripetere l'azione che causa l'errore.

3. Esaminare i log di traccia per identificare dove si verifica il problema.

Monitorare le chiamate di Copilot Studio

Assicurati che il tuo agente Copilot Studio venga attivato correttamente:

1. Connettere l'agente di Copilot Studio ad Application Insights.

2. Monitorare i dati di telemetria per verificare che l'agente riceva richieste da ServiceNow.

3. Controllare la presenza di errori o di comportamenti imprevisti nell'esecuzione dell'agente.

Problemi e soluzioni comuni

• Handoff non viene attivato: verificare che il trasformatore personalizzato sia attivo e che il nodo della conversazione di trasferimento sia configurato correttamente.
• Errori di autenticazione: assicurarsi che il segreto Direct Line sia configurato correttamente in ServiceNow. In particolare, collegare il record delle credenziali in ServiceNow con un record di connessione.
• Timeout della funzione: controlla se Funzione di Azure è in timeout e aumenta le impostazioni di timeout, se necessario.