Overdracht aan ServiceNow

Dit document biedt stapsgewijze instructies voor het maken en verbinden van ServiceNow Virtual Assistant met een Copilot Studio-agent en het escaleren naar ServiceNow Live Agent. Met deze integratie kunt u de mogelijkheden van zowel platforms als generatieve antwoorden gebruiken om uw agentervaring te verbeteren.

Overzicht

Voor de integratie tussen Copilot Studio en ServiceNow zijn de volgende configuratiestappen op hoog niveau vereist:

1. Maak een Azure-functie als relay naar DirectLine.

2. Stel Bot Interconnect in ServiceNow in.

3. Onderwerpen koppelen tussen ServiceNow Virtual Agent en Copilot Studio.

4. DirectLinePrimaryBotIntegrationInboundTransformer uitbreiden.

5. Handoff configureren in Copilot Studio.

Voorwaarden

Voordat u begint, moet u controleren of aan de volgende vereisten is voldaan:

• Een actieve ServiceNow-account met ServiceNow Virtual Agent en ServiceNow Bot Interconnect ingeschakeld. (ServiceNow Yokohama of later is vereist).
• Een Copilot Studio-agent, geconfigureerd met no authentication (dit patroon maakt gebruik van serververificatie met een Direct Line-geheim).
• Beheerderstoegang tot ServiceNow.

Een Azure-functie maken als relay naar DirectLine

De Azure-functie fungeert als een relay, waardoor ServiceNow Bot Interconnect activiteiten (zoals berichten en gebeurtenissen) kan ophalen uit een doorlopend gesprek met een Copilot Studio-agent.

Voorbeeldaanvraag verzonden door 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

Voorbeeldantwoord van de Azure-functie

{
    "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"
}

De functie maken en implementeren

U kunt ervoor kiezen om de v3 Azure-functie te maken en te implementeren, zoals beschreven in de ServiceNow-documentatie of de v4 Azure-functie die beschikbaar is in de GitHub-opslagplaats van Copilot Studio.

Optie 1: De Azure-functie v3 implementeren

Als u de Azure-functie v3 wilt maken en implementeren, volgt u de stappen die worden beschreven in de ServiceNow-documentatie:

1. Maak een JavaScript-functie in Microsoft Azure met behulp van Visual Studio Code.

2. Implementeer de functie in Azure en haal de functie-URL op voor gebruik in ServiceNow Bot Interconnect.

Optie 2: De v4 Azure-functie implementeren

U kunt ook de v4 Azure-functie gebruiken die beschikbaar is in de GitHub-opslagplaats van Copilot Studio:

1. Kloon de opslagplaats vanuit Copilot Studio Samples. De functie bevindt zich onder CopilotStudioSamples/IntegrateWithEngagementHub/ServiceNow/DirectLineAzureFunction.

2. Volg de instructies in Een JavaScript-functie maken in Azure met behulp van Visual Studio Code.

3. Kopieer de functie-URL op de pagina Overzicht van de functie-app.

Bot Interconnect configureren in ServiceNow

1. Haal het direct line-geheim van uw agent op.

2. Voeg de geheime sleutel voor Direct Line toe aan uw Virtual Agent Bot Interconnect-exemplaar.

Onderwerpen afstemmen tussen ServiceNow Virtual Agent en Copilot Studio

1. Als u Copilot Studio-onderwerpen wilt aanroepen, maakt u een Virtual Agent Bot Interconnect-shellonderwerp.

DirectLinePrimaryBotIntegrationInboundTransformer uitbreiden

De ingebouwde DirectLinePrimaryBotIntegrationInboundTransformer code parseert de Copilot Studio-gebeurtenis handoff.initiate niet wanneer het gesprek moet worden overgedragen aan een live agent.

De shouldConnectToAgent functie in DirectLinePrimaryBotIntegrationInboundTransformer retourneert altijd onwaar:

shouldConnectToAgent: function(response) {
    return false;
}

Als u handoff-gebeurtenissen goed wilt afhandelen, maakt u een aangepaste transformator waarmee de standaardtransformatie wordt uitgebreid en de handoff.initiate gebeurtenis wordt gedetecteerd.

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;
    }

De aangepaste transformator maken

1. Schakel in ServiceNow over naar het toepassingsbereik Bot Interconnect .

   1. Selecteer het wereldbolpictogram in de rechterbovenhoek.

   2. Selecteer Bot Interconnect in de lijst met toepassingen.

2. Maak een nieuw script Include.

   1. Navigeer naar Systeemdefinitie>Script Includes.

   2. Klik op Nieuw.

   3. Configureer de volgende instellingen:

   • Naam: CustomDirectLineInboundTransformer
   • API-naam: sn_va_bot_ic.CustomDirectLineInboundTransformer (automatisch gegenereerd)
   • Toepassing: Bot Interconnect (automatisch geselecteerd)
   • Toegankelijk vanaf: Dit toepassingsbereik is alleen toegankelijk
   • Actief: ✓ (ingeschakeld)

3. Vervang de standaardscriptinhoud door de aangepaste transformatieprogrammacode uit de opslagplaats Copilot Studio Samples.

4. Als u het script opnemen wilt opslaan, selecteert u Verzenden.

De Bot Interconnect-configuratie bijwerken

1. Navigeer naar Workflow Studio.

   1. Navigeer in ServiceNow naar Workflow Studio.

   2. Zoek onder Acties naar Direct Line Primary Bot Integration Inbound Transformer.

2. Wijzig de actie van de transformator.

   1. Open de actie Direct Line Primary Bot Integration Inbound Transformer.

   2. Maak in de scripteditor commentaar op de standaardtransformatie en vervang deze door een aanroep naar uw aangepaste transformator.

   (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. Sla de wijzigingen op in de actie en publiceer deze.

Handoff configureren

Als u de overdracht naar een ServiceNow Live Agent wilt inschakelen, voegt u een gespreksknooppunt overdragen toe aan het onderwerp Escaleren van uw agent.

1. Open uw agent in Copilot Studio en navigeer naar Onderwerpen>systeem>escaleren.

2. Selecteer + (knooppunt toevoegen) >Onderwerpbeheer>Gesprek overdragen.

3. Sla je onderwerp op en publiceer je agent.

Het gespreksknooppunt Overdragen verzendt een handoff.initiate gebeurtenis die door de aangepaste transformator van ServiceNow wordt gedetecteerd en verwerkt.

Voorbeeld van YAML-bestand voor escalerend onderwerp

U kunt ook de volgende YAML-configuratie importeren voor een volledig escalerend onderwerp met overdrachtsmogelijkheden:

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

Probleemoplossingsproces

Als er fouten optreden in de chatwidget ServiceNow Virtual Agent, volgt u deze stappen voor probleemoplossing:

Azure Function-logboeken controleren

1. Controleer of uw Azure-functie correct werkt en geen fouten retourneert.

2. Realtime logboeken weergeven met behulp van streaminglogboeken van Azure Functions.

3. Controleer Application Insights op gedetailleerde telemetrie- en foutgegevens.

ServiceNow-foutopsporing inschakelen

Gebruik de ingebouwde hulpprogramma's voor foutopsporing van ServiceNow om de uitvoeringsstroom te traceren:

1. Schakel in ServiceNow de Script Tracer in.

2. Herhaal de actie die de fout veroorzaakt.

3. Controleer de traceringslogboeken om te bepalen waar het probleem zich voordoet.

Copilot Studio-aanroepen bewaken

Zorg ervoor dat uw Copilot Studio-agent correct wordt aangeroepen:

1. Verbind uw Copilot Studio-agent met Application Insights.

2. Controleer de telemetrie om te bevestigen dat de agent aanvragen ontvangt van ServiceNow.

3. Controleer op fouten of onverwacht gedrag bij de uitvoering van de agent.

Veelvoorkomende problemen en oplossingen

• Handoff wordt niet geactiveerd: controleer of de aangepaste transformator actief is en of het overdrachtsknooppunt van het gesprek juist is geconfigureerd
• Verificatiefouten: zorg ervoor dat het Direct Line-geheim juist is geconfigureerd in ServiceNow. De referentierecord in ServiceNow moet met name worden gekoppeld aan een verbindingsrecord.
• Functietime-out: controleer of er een time-out optreedt voor de Azure-functie en verhoog de time-outinstellingen indien nodig