Transferência para o ServiceNow

Este artigo fornece instruções passo a passo sobre como criar e conectar um Assistente Virtual do ServiceNow a um agente do Copilot Studio e escalonar para o ServiceNow Live Agent. Use essa integração para aproveitar os recursos de ambas as plataformas e usar respostas generativas para aprimorar a experiência do agente.

Visão geral

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 o DirectLine.

2. Configurar o Bot Interconnect no ServiceNow.

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

4. Estenda DirectLinePrimaryBotIntegrationInboundTransformer.

5. Configure a transferência no Copilot Studio.

Pré-requisitos

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

• Uma conta do ServiceNow ativa com o Agente Virtual do ServiceNow habilitado e a Interconexão do Bot do ServiceNow habilitada. (Necessário ServiceNow Yokohama ou posterior).
• Um agente do Copilot Studio configurado com no authentication (esse padrão usa a autenticação de servidor para servidor com um segredo de Linha Direta).
• Acesso de administrador ao ServiceNow.

Criar uma função do Azure como uma retransmissão para o 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 contínua com um agente do Copilot Studio.

Solicitação de exemplo 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

Resposta de exemplo do Azure Function

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

Criando e implantando a função

Você pode criar e implantar a função do Azure v3 descrita na documentação do ServiceNow ou a função do 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 a função do Azure 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 de 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ções, copie a URL da função.

Configurar a interconexão de bot no ServiceNow

1. Obtenha o código secreto da linha direta do seu agente.

2. Adicione a chave secreta do Direct Line à instância de Interconexão do Bot do Agente Virtual.

Mapear tópicos entre ServiceNow Virtual Agent e Copilot Studio

1. Para chamar tópicos do Copilot Studio, crie um tópico do shell de Interconexão de Bot do Agente Virtual.

Estender DirectLinePrimaryBotIntegrationInboundTransformer

O DirectLinePrimaryBotIntegrationInboundTransformer integrado não analisa o evento handoff.initiate do Copilot Studio quando a conversa precisa ser entregue a um agente humano.

A shouldConnectToAgent função em DirectLinePrimaryBotIntegrationInboundTransformer sempre retorna falso:

shouldConnectToAgent: function(response) {
    return false;
}

Para lidar corretamente com eventos de entrega, crie um transformador personalizado que estenda o transformador padrão e detecte 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 escopo do aplicativo Interconexão de Bot.

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

   2. Selecione Interconexão de Bot na lista de aplicativos.

2. Crie uma nova inclusão de script.

   1. Vá para Definição do Sistema>Inclusões de Script.

   2. Selecione Novo.

   3. Defina as seguintes configurações:

   • Nome: CustomDirectLineInboundTransformer
   • Nome da API: sn_va_bot_ic.CustomDirectLineInboundTransformer (gerado automaticamente)
   • Aplicativo: Interconexão de Bot (seleção automática)
   • Acessível somente neste escopo do aplicativo
   • Ativo: ✓ (verificado)

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

4. Selecione Enviar para salvar a Inclusão de Script.

Atualizar a configuração da interconexão de bot

1. Vá para o Workflow Studio.

   1. No ServiceNow, vá para o Workflow Studio.

   2. Em Ações, localize o Transformador de Entrada de Integração de Bot Principal do Direct Line.

2. Altere a ação do transformador.

   1. Abra a ação Transformador de Entrada de Integração do Bot Primário do Direct Line.

   2. No editor de scripts, comente o transformador padrão e substitua-o por uma chamada para o 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 habilitar a transferência para um Agente Humano do ServiceNow, adicione um nó Transferir conversa ao tópico Escalonamento do agente.

1. No Copilot Studio, abra seu agente e vá para o Topics>System>Escalate.

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

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

O nó Transferir Conversa envia um handoff.initiate evento que o transformador personalizado do ServiceNow detecta e processa.

YAML do tópico de escalonamento de amostra

Você também pode importar a seguinte configuração YAML para um tópico de escalonamento completo com capacidade 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 logs de funções do Azure

1. Verifique se a função do Azure está funcionando corretamente e se não está retornando erros.

2. Exiba logs em tempo real usando logs de streaming do Azure Functions.

3. Verifique o Application Insights para informações detalhadas de telemetria e erros.

Habilitar depuração do ServiceNow

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

1. Habilitar o Rastreamento de Script no ServiceNow.

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

3. Examine os logs de rastreamento para identificar onde o problema ocorre.

Monitorar invocações do Copilot Studio

Verifique se o agente do Copilot Studio foi invocado corretamente:

1. Conecte o 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 comuns e soluções

• A transferência não é disparada: Verifique se o transformador personalizado está ativo e se o nó de conversa de transferência está configurado corretamente.
• Erros de autenticação: verifique se o segredo da Linha Direta está configurado corretamente no ServiceNow. Especificamente, vincule o registro de credencial no ServiceNow com um registro de conexão.
• Tempo limite da função: verifique se a Função do Azure está atingindo o tempo limite e aumente as configurações de tempo limite, se necessário.