Incorporación del agente en aplicaciones web

Editar en línea

El chat integrado permite a las aplicaciones integrar agentes directamente en las experiencias web y de los clientes. Esta integración admite comunicaciones seguras, personalización flexible de la interfaz de usuario y gestión de eventos para ofrecer experiencias conversacionales enriquecidas, e introduce importantes consideraciones de seguridad para garantizar que el acceso, la identidad y el contexto del usuario se gestionen correctamente.

Este procedimiento define los requisitos previos y los pasos que debe seguir para integrar el agente en una aplicación web.

Entornos de desarrollo y producción para chat integrado

Los entornos de prueba y de producción influyen en la versión del agente que se desea invocar mediante el script integrado y en cómo se reflejan los cambios en tiempo de ejecución. Comprender a qué entorno se dirige su script integrado ayuda a evitar pruebas involuntarias en producción o mostrar un comportamiento incompleto a los usuarios.

  • Cheque

El entorno de pruebas está destinado al desarrollo y la validación. Los scripts incrustados que se copian desde Draft están destinados específicamente a la variante de borrador, donde se pueden probar los cambios de configuración, la lógica de conversación y el comportamiento de la interfaz de usuario sin afectar a los usuarios.

  • En directo

El entorno de producción es la versión implementada y lista para su uso de tu agente. Las incrustaciones en vivo proporcionan un comportamiento estable y versionado adecuado para entornos de producción. Los cambios que realices en el borrador no se reflejarán en la versión activa hasta que implementes explícitamente tu agente.

Requisitos previos

Para ejecutar correctamente el agente dentro del chat integrado, su aplicación debe cumplir los siguientes requisitos:

  • Incluir un componente del lado del servidor (local o en la nube)

Se necesita un servidor para almacenar y utilizar de forma segura las claves privadas, firmar solicitudes e interactuar con las API de watsonx Orchestrate.

  • Incluye un contenedor root HTML

La página de incrustación debe contener un elemento HTML con el identificador root.

  • Utilizar el modo estricto de HTML

La página que incorpora el chat web debe declarar el modo estricto de HTML incluyendo la <!DOCTYPE html> directiva.

  • Configurar la seguridad del chat integrado

La seguridad está habilitada de forma predeterminada tanto en el entorno de prueba como en el de producción, pero no está configurada. Debes configurarlo explícitamente tal y como se describe en la sección «Configuración de la seguridad para el chat integrado ». Es posible que pueda ver el widget de chat en la aplicación web, pero no se inicializará a menos que el servicio configure y valide las claves criptográficas necesarias.

  • Incrusta el script dentro del <body> elemento

Coloca el script dentro de la <body> etiqueta para garantizar que el DOM esté disponible cuando se ejecute el script y que el elemento raíz se pueda resolver correctamente en el momento de la inicialización.

Procedimiento para integrar agentes en aplicaciones web

Puede integrar el widget de chat para un agente en su aplicación utilizando el script integrado generado desde la interfaz de usuario del agente. Si prefieres generar el script mediante un comando de la interfaz de línea de comandos, consulta la sección «Integración de agentes con aplicaciones web» en la documentación del _ IBMwatsonx Orchestrate Agent Development Kit_. El siguiente procedimiento se centra en el flujo de trabajo basado en la interfaz de usuario.

Nota:

  • Para la implementación local de IBM watsonx Orchestrate :

  • Versión 5.2.1: No se admite la copia del script incrustado desde la interfaz de usuario del agente. Utilice la documentación de ADK para obtener el script integrado. Para obtener más información, consulta «Incorporación del chat web de Agent ».

  • Versiones 5.2.2 y posteriores: puede copiar directamente los scripts incrustados desde la interfaz de usuario del agente.

  1. Acceda a la configuración del agente:

    • Vaya a la página de configuración del agente.

    • Vaya a Canales > Agente integrado.

  2. Seleccione el entorno:

    • Utiliza el modo Borrador para probar y obtener una vista previa del widget de chat en la aplicación web.

    • Utilice el modo Live para obtener el script del agente implementado. Esta pestaña permanece desactivada hasta que se despliega el agente.

  3. Copie el script incrustado:

    • Haga clic en Copiar al portapapeles para copiar el script generado.

El siguiente código es un ejemplo del script incrustado:

    <script>
      window.wxOConfiguration = {
        orchestrationID: "your-orgID_orchestrationID", // Adds control over chat display mode (e.g., fullscreen)
        hostURL: "https://dl.watson-orchestrate.ibm.com", // or region-specific host
        rootElementID: "root",
        showLauncher: false,
        deploymentPlatform: "ibmcloud", // Required for IBM Cloud embed, can be skipped for other embed scenarios
        crn: "your-org-crn", // Required for IBM Cloud embed, can be skipped for other embed scenarios. For more information, see https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID&interface=ui
        chatOptions: {
          agentId: "your-agent-id",
          agentEnvironmentId: "your-agent-env-id",
        },
      };
      setTimeout(function () {
        const script = document.createElement("script");
        script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
        script.addEventListener("load", function () {
          wxoLoader.init();
        });
        document.head.appendChild(script);
      }, 0);
    </script>

  1. Añade el script a tu página web:

    • Edita el código HTML de la página donde quieres que aparezca el widget de chat.

    • Pega el script incrustado dentro de la <body> etiqueta, lo más cerca posible de la etiqueta de </body> cierre para obtener un rendimiento óptimo en la carga de la página.

    • Asegúrate de que root el elemento esté presente.

Ejemplo de estructura HTML:

    <body>
      <div id="root"></div>
      <script src="path-to-embed-script.js"></script>
    </body>

Ahora puede abrir el sitio web para obtener una vista previa del widget de chat y probar la integración.

Qué hacer a continuación

Pega el mismo script en cada página donde quieras que aparezca el chat del agente. No incluyas el script más de una vez en la misma página para evitar conflictos de carga.

Utiliza las API disponibles para aplicar estilos y diseños personalizados a la interfaz de usuario del chat, habilitar comentarios o gestionar variables de contexto para personalizar las conversaciones de los usuarios con un agente. Para obtener más información, consulte los siguientes recursos: