Entregar à ServiceNow

Este artigo fornece instruções passo a passo sobre como criar e ligar um Assistente Virtual ServiceNow a um agente do Copilot Studio e escalar para o Agente ao Vivo do ServiceNow. Use esta integração para tirar partido das capacidades de ambas as plataformas e utilize respostas generativas para melhorar a experiência do seu agente.

Overview

A integração entre o Copilot Studio e o ServiceNow requer as seguintes etapas de configuração de alto nível:

1. Crie uma Função do Azure como uma retransmissão para DirectLine.

2. Configure a interconexão de bots no ServiceNow.

3. Mapeie tópicos entre o ServiceNow Virtual Agent e o Copilot Studio.

4. Extender DirectLinePrimaryBotIntegrationInboundTransformer.

5. Configure handoff em Copilot Studio.

Pré-requisitos

Antes de começar, certifique-se de que tem os seguintes pré-requisitos:

• Uma conta ServiceNow ativa com o ServiceNow Virtual Agent habilitado e a Interconexão ServiceNow Bot habilitada. Necessário o ServiceNow Yokohama ou posterior.
• Um agente do Copilot Studio configurado com no authentication (este padrão utiliza autenticação servidor-a-servidor com um segredo Direct Line).
• Acesso de administrador ao ServiceNow.

Criar uma função do Azure como uma retransmissão para DirectLine

A Função do Azure atua como uma retransmissão, permitindo que o ServiceNow Bot Interconnect recupere atividades (como mensagens e eventos) de uma conversa em andamento com um agente do Copilot Studio.

Solicitação de amostra enviada pelo 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

Exemplo de resposta da Função do 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"
}

Criação e implementação da função

Pode criar e implementar a função Azure v3 descrita na documentação ServiceNow ou a função Azure v4 disponível no repositório GitHub do Copilot Studio.

Opção 1: Implantar a função do Azure v3

Para criar e implantar o Azure Function v3, siga as etapas descritas na documentação do ServiceNow:

1. Crie uma função JavaScript no Microsoft Azure usando o Visual Studio Code.

2. Implante a função no Azure e recupere a URL da função para uso no ServiceNow Bot Interconnect.

Opção 2: Implantar a função do Azure v4

Como alternativa, você pode usar a Função do Azure v4 disponível no repositório GitHub do Copilot Studio:

1. Clone o repositório do Copilot Studio Samples. A função está localizada em CopilotStudioSamples/contact-center/servicenow/DirectLineAzureFunction.

2. Siga as instruções em Criar uma função JavaScript no Azure usando o Visual Studio Code.

3. Na página Visão geral do aplicativo de função, copie o URL da função.

Configurar a interconexão de bots no ServiceNow

1. Obtenha o segredo da Linha Direta do seu agente.

2. Adicione a chave secreta do Direct Line à sua instância do Virtual Agent Bot Interconnect.

Mapear tópicos entre o ServiceNow Virtual Agent e o Copilot Studio

1. Para chamar tópicos do Copilot Studio, crie um tópico do shell Virtual Agent Bot Interconnect.

Expandir DirectLinePrimaryBotIntegrationInboundTransformer

O DirectLinePrimaryBotIntegrationInboundTransformer incorporado não analisa o evento do Copilot Studio handoff.initiate quando a conversação tem de ser transferida para um agente em direto.

A função shouldConnectToAgent em DirectLinePrimaryBotIntegrationInboundTransformer devolve sempre falso.

shouldConnectToAgent: function(response) {
    return false;
}

Para lidar corretamente com eventos de transferência, crie um transformador personalizado que estenda o transformador padrão e detete o handoff.initiate evento.

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

Criar o transformador personalizado

1. No ServiceNow, alterne para o âmbito da aplicação Bot Interconnect .

   1. Selecione o ícone do globo no canto superior direito.

   2. Selecione Bot Interconnect na lista de aplicativos.

2. Crie um novo Script Include.

   1. Vá para System Definition>Script Includes.

   2. Selecione Novo.

   3. Defina as seguintes configurações:

   • Nome: CustomDirectLineInboundTransformer
   • Nome da API: sn_va_bot_ic.CustomDirectLineInboundTransformer (gerado automaticamente)
   • Aplicação: Bot Interconnect (selecionado automaticamente)
   • Acessível a partir de: Apenas o âmbito desta aplicação
   • Ativo: ✓ (verificado)

3. Substitua o conteúdo do script padrão pelo código do transformador personalizado do repositório Copilot Studio Samples.

4. Selecione Enviar para guardar o Script Include.

Atualizar a configuração do Bot Interconnect

1. Vai ao Workflow Studio.

   1. No ServiceNow, vai ao Workflow Studio.

   2. Em Ações, encontre Transformador de Entrada com Integração Primária de Bots de Linha Direta.

2. Muda a ação do transformador.

   1. Abra a ação Direct Line Primary Bot Integration Inbound Transformer.

   2. No editor de scripts, comente o transformador padrão e substitua-o por uma chamada para o seu transformador personalizado.

   (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. Salve as alterações na ação e publique.

Configurar transferência

Para ativar a transferência para um agente em direto do ServiceNow, adicione um nó de Transferir conversação ao tópico Escalar do agente.

1. No Copilot Studio, abre o teu agente e vai a Tópicos>Sistema>Escalar.

2. Selecione + (Adicionar nó) >Gerenciamento de tópicos>Transferir conversa.

3. Salve seu tópico e publique seu agente.

O nó Transferir conversação envia um handoff.initiate evento que o transformador personalizado do ServiceNow deteta e processa.

Exemplo do tópico de Escalada YAML

Você também pode importar a seguinte configuração do YAML para um tópico completo do Escalate com recursos de transferência:

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

Solução de problemas

Se você encontrar erros no widget de chat do ServiceNow Virtual Agent, siga estas etapas de solução de problemas:

Verificar os logs da Função do Azure

1. Verifica se a tua Função Azure está a funcionar corretamente e não está a devolver erros.

2. Veja registos em tempo real usando os registos de streaming do Funções do Azure.

3. Verifique o Application Insights para obter informações detalhadas sobre telemetria e erro.

Ativar depuração do ServiceNow

Use as ferramentas de depuração internas do ServiceNow para rastrear o fluxo de execução:

1. Habilite o Rastreador de Script no ServiceNow.

2. Repita a ação que está causando o erro.

3. Revise os registos de rastreamento para identificar onde ocorre o problema.

Monitorar invocações do Copilot Studio

Certifique-se de que o seu agente do Copilot Studio é invocado corretamente:

1. Conecte seu agente do Copilot Studio ao Application Insights.

2. Monitore a telemetria para confirmar se o agente está recebendo solicitações do ServiceNow.

3. Verifique se há erros ou comportamentos inesperados na execução do agente.

Problemas e soluções comuns

• O handoff não é acionado: Verifique se o transformador personalizado está ativo e se o nó Transferir conversação está devidamente configurado.
• Erros de autenticação: verifique se o segredo da Linha Direta está configurado corretamente no ServiceNow. Especificamente, ligue o registo de credencial no ServiceNow a um registo de ligação.
• Tempo limite da função: Verifique se a Função do Azure está a exceder o tempo limite e aumente as definições de tempo limite, se necessário.