Derivar las conversaciones a ServiceNow

Conecta el Agente Virtual de ServiceNow con un agente de Copilot Studio y configura la transferencia a un agente humano en ServiceNow. La integración utiliza una función de Azure para retransmitir actividades de Direct Line y un transformador ServiceNow personalizado para detectar eventos de traspaso.

Overview

La integración entre Copilot Studio y ServiceNow requiere los siguientes pasos de configuración de alto nivel:

1. Despliega una función de Azure como relé a Direct Line.

2. Configuración de la interconexión de bots en ServiceNow.

3. Asignar temas entre Virtual Agent de ServiceNow y Copilot Studio.

4. Extiende DirectLinePrimaryBotIntegrationInboundTransformer.

5. Configura el handoff en Copilot Studio.

Prerequisites

Antes de comenzar, asegúrese de que tiene los siguientes requisitos previos:

• Una cuenta activa de ServiceNow con ServiceNow Virtual Agent y ServiceNow Bot Interconnect activados. Necesitas ServiceNow Yokohama o más tarde.
• Un agente de Copilot Studio configurado sin autenticación. Esta configuración se aplica al inicio de sesión por parte del usuario final; el relé servidor a servidor utiliza un secreto Direct Line para autorizar el acceso al canal.
• Acceso de administrador a ServiceNow.

Crear una función de Azure como relé a Direct Line

La función Azure actúa como un relé para que ServiceNow Bot Interconnect pueda recuperar actividades, como mensajes y eventos, de una conversación continua con un agente de Copilot Studio.

Solicitud de ejemplo enviada por 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

Respuesta de ejemplo de la función de 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"
}

Crear y desplegar la función

Puede crear e implementar la función de Azure v3 descrita en la documentación de ServiceNow o la función de Azure v4 disponible en el repositorio de GitHub de Copilot Studio.

Opción 1: Implementación de la función de Azure v3

Para crear e implementar la función de Azure v3, siga los pasos descritos en la documentación de ServiceNow:

1. Crear una función de JavaScript en Microsoft Azure usando Visual Studio Code.

2. Implemente la función en Azure y recupere la dirección URL de la función para su uso en ServiceNow Bot Interconnect.

Opción 2: Implementación de la función de Azure v4

Como alternativa, puede usar la función de Azure v4 disponible en el repositorio de GitHub de Copilot Studio:

1. Clona el repositorio de muestras de Copilot Studio. Abre el proyecto proporcionado bajo contact-center/servicenow/DirectLineAzureFunction en Visual Studio Code.

2. Sigue las instrucciones de configuración del proyecto. Crea una aplicación de funciones en Azure y despliega el proyecto de relé proporcionado. No sustituyas el relé por una nueva función HTTP generada por plantillas. Aprende más en Desplegar archivos de proyecto.

3. Tras el despliegue, copia la URL de la función HTTP de relé para usarla en ServiceNow Bot Interconnect. Usa el endpoint de la función, no la URL base de la app de la función. Aprende más en Obtener la URL de una función activada por HTTP en Azure.

Configuración de la interconexión de bots en ServiceNow

1. Obtenga el secreto de Direct Line de su agente

2. Agregue la clave secreta de Direct Line para su instancia de Virtual Agent Bot Interconnect.

Mapeo de temas entre ServiceNow Virtual Agent y Copilot Studio

1. Crea un tema shell de interconexión de Virtual Agent Bot para llamar a temas de Copilot Studio.

Extender DirectLinePrimaryBotIntegrationInboundTransformer

El elemento integrado DirectLinePrimaryBotIntegrationInboundTransformer no analiza el evento Copilot Studio handoff.initiate cuando la conversación necesita pasarse a un agente en vivo.

La shouldConnectToAgent función de DirectLinePrimaryBotIntegrationInboundTransformer siempre devuelve false:

shouldConnectToAgent: function(response) {
    return false;
}

Para controlar correctamente los eventos de entrega, cree un transformador personalizado que extienda el transformador predeterminado y detecte el 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;
    }

Creación del transformador personalizado

1. En ServiceNow, cambie al ámbito de la aplicación Interconexión de Bots.

   1. Seleccione el icono de globo en la esquina superior derecha.

   2. Seleccione Bot Interconnect (Interconexión de bots ) en la lista de aplicaciones.

2. Cree un nuevo Script Include.

   1. Vaya a Definición del Sistema>Incluir Script.

   2. Seleccione Nuevo.

   3. Configure los valores siguientes:

   • Nombre: CustomDirectLineInboundTransformer
   • Nombre de LA API: sn_va_bot_ic.CustomDirectLineInboundTransformer (generado automáticamente)
   • Aplicación: interconexión del bot (selección automática)
   • Accesible desde: este ámbito de aplicación solo
   • Activo: Seleccionado

3. Reemplace el contenido de script predeterminado por el código de transformador personalizado del repositorio de ejemplos de Copilot Studio.

4. Seleccione Enviar para guardar la inclusión del script.

Actualización de la configuración de interconexión de bots

1. Vaya a Workflow Studio.

   1. En ServiceNow, vaya a Workflow Studio.

   2. En Acciones, busque Direct Line Primary Bot Integration Inbound Transformer.

2. Cambie la acción del transformador.

   1. Abra la acción Direct Line Primary Bot Integration Inbound Transformer.

   2. En el editor de scripts, comente el transformador predeterminado y reemplácelo por una llamada a su 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. Guarde los cambios en la acción y publique.

Configurar entrega

Para configurar la transferencia a un agente humano en ServiceNow, añade un nodo Transfer conversation al tema Escalate de tu agente.

1. En Copilot Studio, abra su agente y vaya a Temas>Sistema>Escalar.

2. Seleccione + (Agregar nodo) >gestión de temas>transferir conversación.

3. Guarde su tema y publique su agente.

El nodo Transferir conversación envía un handoff.initiate evento que el transformador personalizado de ServiceNow detecta y procesa.

YAML de tema de escalación de ejemplo

También puede importar la siguiente configuración de YAML para un tema de Escalate completo con capacidades de transferencia.

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

Si se producen errores en el widget de chat del agente virtual de ServiceNow, siga estos pasos de solución de problemas:

Comprobación de los registros de funciones de Azure

1. Compruebe que la función de Azure funciona correctamente y no devuelve errores.

2. Vea los registros en tiempo real mediante los registros de streaming de Azure Functions.

3. Consulte Application Insights para obtener información detallada sobre telemetría y errores.

Activar la depuración de ServiceNow

Use las herramientas de depuración integradas de ServiceNow para realizar un seguimiento del flujo de ejecución:

1. Activa Script Tracer en ServiceNow.

2. Repita la acción que está causando el error.

3. Revise los registros de seguimiento para identificar dónde se produce el problema.

Supervisión de invocaciones de Copilot Studio

Asegúrate de que tu agente de Copilot Studio sea invocado correctamente:

1. Conecte el agente de Copilot Studio a Application Insights.

2. Supervise la telemetría para confirmar que el agente recibe solicitudes de ServiceNow.

3. Compruebe si hay errores o comportamiento inesperado en la ejecución del agente.

Problemas y soluciones comunes

• Handoff no se desencadena: compruebe que el transformador personalizado está activo y que el nodo de transferencia de conversación está configurado correctamente.
• Errores de autenticación: asegúrese de que el secreto de Direct Line está configurado correctamente en ServiceNow. En concreto, vincule el registro de credenciales en ServiceNow con un registro de conexión.
• Tiempo de espera de la función: compruebe si la función de Azure está agotando el tiempo de espera y aumente la configuración de tiempo de espera si es necesario.