Agente de Conocimiento de Jitterbit

Descripción general

Jitterbit proporciona el Agente de Conocimiento a los clientes a través del Marketplace de Jitterbit. Este agente está diseñado para permitir que el equipo interno de la organización obtenga respuestas inteligentes desde los datos internos de la organización. El agente utiliza la técnica de Generación Aumentada por Búsqueda (RAG), que combina el razonamiento del LLM con acceso a herramientas y fuentes de datos externas. Realiza lo siguiente:

• Se conecta y obtiene información de las siguientes fuentes utilizando Jitterbit Studio:

  • Páginas de Atlassian Confluence
  • Problemas de Atlassian Jira
  • Documentos de Google Drive
  • Casos de soporte de Salesforce (desde el objeto Case)

• Se integra con un LLM para potenciar un chatbot de IA inteligente utilizando datos de las fuentes anteriores, accedidos a través de una API personalizada creada con Jitterbit API Manager.

Este documento explica cómo configurar y operar este agente de IA. Cubre la arquitectura y los requisitos previos, los ejemplos de prompts que muestran lo que puede hacer el agente, y los pasos para instalar, configurar y operar el agente de IA.

Arquitectura del agente de IA

El siguiente diagrama muestra la arquitectura implementada en el Agente de Conocimiento:

Flujo de datos del agente

Flujos de trabajo de carga inicial de datos y mantenimiento de datos

Requisitos previos

Para usar el Agente de Conocimiento, se requieren o asumen los siguientes componentes en el diseño del agente.

Componentes de Harmony

Debes contar con una licencia de Jitterbit Harmony con acceso a los siguientes componentes:

• Jitterbit Studio
• Jitterbit API Manager
• Agente de Conocimiento de Jitterbit adquirido como complemento de licencia

Puntos de conexión compatibles

Los siguientes puntos de conexión se incorporan al diseño del agente.

Modelo de lenguaje grande (LLM)

El agente de IA utiliza Azure OpenAI como proveedor de LLM. Para usar Azure OpenAI, debes contar con una suscripción de Microsoft Azure con permisos para crear y administrar los siguientes recursos:

• Recurso de Azure OpenAI con un modelo gpt-4o o gpt-4.1 implementado.
• Azure Storage con un contenedor de Blob para almacenar los datos obtenidos.
• Azure AI Search con un servicio de búsqueda que se puede configurar con un índice e indexador.

Base de conocimientos

Puedes usar cualquiera o todos estos puntos de conexión como base de conocimientos para este agente de IA:

• Atlassian Confluence: La fuente de páginas de Confluence.
• Atlassian Jira: La fuente de problemas de Jira.
• Google Drive: La fuente de archivos almacenados en una unidad compartida de Google.
• Salesforce: La fuente de tus casos de soporte al cliente desde el objeto Case.

Interfaz de chat

El diseño del agente incorpora Slack como interfaz de chat para interactuar con el agente de IA. Si deseas usar una aplicación diferente como interfaz de chat, en este agente de IA se incluyen un flujo de trabajo separado e instrucciones para una configuración genérica de API.

Ejemplos de prompts

A continuación se muestran ejemplos de prompts que el Agente de Conocimiento puede manejar con acceso a los datos apropiados. El agente puede encontrar información en cualquiera o en todos los puntos de conexión conectados.

• "Estoy teniendo un problema con el componente 'ABC'. ¿Puedes ayudarme con esto?"
• "¿Cómo puedo conectarme a una base de datos MySQL usando JDBC?"
• "¿Puedes darme detalles sobre el ticket de Jira número 123?"
• "¿Hay algún ticket de Jira relacionado con el conector SQL?"
• "¿Cuál es la política de seguridad para instalar software en mi computadora de trabajo?" (Puede haber un documento en Google Drive o una página de Confluence sobre este tema.)

Instalación, configuración y funcionamiento

Sigue estos pasos para instalar, configurar y operar este agente de IA:

1. Descarga las personalizaciones e instala el proyecto de Studio.
2. Revisa los flujos de trabajo del proyecto.
3. Crea recursos de Microsoft Azure.
4. Crea la aplicación de Slack.
5. Configura una cuenta de servicio de Google y una unidad compartida.
6. Configura las variables del proyecto.
7. Prueba las conexiones.
8. Implementa el proyecto.
9. Crea la API personalizada de Jitterbit.
10. Revisa los flujos de trabajo del proyecto.
11. Activa los flujos de trabajo del proyecto.
12. Solución de problemas.

Descarga las personalizaciones e instala el proyecto

Sigue estos pasos para descargar los archivos de personalización e instalar el proyecto de Studio:

1. Inicia sesión en el portal de Harmony en https://login.jitterbit.com y abre Marketplace.

2. Localiza el agente de IA llamado Jitterbit Knowledge Agent. Para localizarlo, puedes usar la barra de búsqueda o, en el panel Filtros bajo Tipo, selecciona Agente de IA para limitar la visualización a los agentes de IA disponibles.

3. Haz clic en el enlace Documentación del agente de IA para abrir su documentación en una pestaña separada. Mantén la pestaña abierta para consultarla después de iniciar el proyecto.

4. Haz clic en Iniciar Proyecto para abrir un diálogo de configuración de dos pasos para descargar personalizaciones e importar el agente de IA como un proyecto de Studio.

   Nota

   Si aún no has comprado el agente de IA, se mostrará Obtener agente en su lugar. Haz clic en él para abrir un diálogo informativo y luego haz clic en Enviar para que un representante se comunique contigo sobre la compra del agente de IA.

5. En el paso de configuración 1, Descargar Personalizaciones, se proporcionan los siguientes archivos para facilitar la configuración del índice e indexador en Azure AI Search y para crear la aplicación de Slack. Selecciona los archivos y haz clic en Descargar Archivos:

   • Archivos de definición JSON del índice e indexador de Azure AI Search

     • Azure_AI_Search_Datasource_Definition.json
     • Azure_AI_Search_Index_Definition.json
     • Azure_AI_Search_Indexer_Definition.json

   • Archivo de manifiesto de la aplicación de Slack

     • slack_app_manifest.json

   Consejo

   El diálogo de configuración incluye una advertencia para no importar la plantilla antes de aplicar personalizaciones de punto de conexión. Esta advertencia no aplica a este agente de IA y puede ignorarse. Sigue el orden recomendado de pasos en esta documentación.

   Haz clic en Siguiente.

6. En el paso de configuración 2, Crear un Nuevo Proyecto, selecciona un entorno donde quieras crear el proyecto de Studio y luego haz clic en Crear Proyecto.

7. Se muestra un diálogo de progreso. Después de que indique que el proyecto se ha creado, usa el enlace del diálogo Ir a Studio o abre el proyecto directamente desde la página Proyectos de Studio.

Crea recursos de Microsoft Azure

Crea los siguientes recursos de Microsoft Azure y conserva la siguiente información para configurar el agente de IA. Para crear y administrar estos recursos, debes tener una suscripción de Microsoft Azure con los permisos apropiados.

Contenedor de Azure Blob

Debes crear un contenedor de Azure Blob para almacenar detalles de clientes. Los datos del contenedor de Blob se indexarán en Azure AI Search usando un índice e indexador.

Necesitarás la URL de SAS del contenedor para usar en la determinación de los valores de las variables del proyecto Azure Blob Storage. Para generar la URL de SAS:

1. En el portal de Azure, ve a Cuentas de almacenamiento y abre la cuenta de almacenamiento específica.
2. Desde el menú de recursos en Almacenamiento de datos, selecciona Contenedores y abre el contenedor específico.
3. Desde el menú de recursos en Configuración, selecciona Tokens de acceso compartido.
4. Usa el menú Permisos para verificar que la URL de firma de acceso compartido (SAS) para este contenedor tenga un mínimo de permisos de Lectura y Escritura:

1. Haz clic en Generate SAS token and URL.
2. Copia la Blob SAS URL que se muestra en la parte inferior.
3. Determina los valores de las variables del proyecto Azure Blob Storage a partir de la URL de SAS. La URL de SAS tiene el formato {{ azure_blob_base_url }}/{{ Azure_Blob_Container_Name }}?{{ azure_blob_sas_token }}.

Si usas los archivos de definición JSON incluidos en los archivos de personalización del agente de IA para generar el índice e indexador, también necesitarás la clave de cuenta de Azure Blob Storage. Para ver las claves de acceso de la cuenta:

1. En Azure Portal, ve a Cuentas de almacenamiento y abre la cuenta de almacenamiento específica.
2. Desde el menú de recursos en Security + networking, selecciona Access keys.

3. Haz clic en Show keys para revelar la clave de acceso a usar durante la configuración de Azure AI Search.

   

Servicio Azure AI Search

Debes crear un servicio Azure AI Search y configurar su índice e indexador para procesar los datos del contenedor Blob.

Necesitarás la URL y la clave de API del servicio Azure AI Search para determinar los valores de las variables del proyecto Azure AI Search:

• URL: Para obtener el valor a usar en azure_ai_search_url, consulta la documentación de Azure Get service information.
• Clave de API: Para obtener el valor a usar en azure_ai_search_api_key, consulta la documentación de Azure Configure role-based access.

Puedes usar los archivos de definición JSON incluidos en los archivos de personalización del agente de IA para generar el índice e indexador, o puedes crearlos tú mismo.

Si usas los archivos de definición proporcionados, debes reemplazar los siguientes marcadores de posición con tus propios valores de configuración:

Azure_AI_Search_Indexer_Definition.json

Azure_AI_Search_Datasource_Definition.json

Recurso Azure OpenAI

Debes crear un recurso Azure OpenAI e implementar un modelo gpt-4o o gpt-4.1 a través de Azure AI Foundry Portal.

Necesitarás el nombre de la implementación, la URL del punto de conexión de Azure OpenAI y la clave de API para determinar los valores de las variables del proyecto Azure OpenAI. Para encontrar estos valores:

1. En el portal de Azure AI Foundry, abre el recurso específico de OpenAI.

2. Los valores que debes utilizar para la URL del punto de conexión (azure_openai_base_url) y la clave de API (azure_openai_api_key) se muestran en la página de inicio del recurso:

   

3. En el menú de navegación bajo Recursos compartidos, selecciona Implementaciones. Se muestra el nombre de la implementación (Azure_OpenAI_Deployment_Name).

Crear la aplicación de Slack

Para crear la interfaz de chat del Agente de Conocimiento en Slack, sigue estos pasos:

1. Crea una aplicación de Slack utilizando el archivo de manifiesto de aplicación de Slack (slack_app_manifest.json) proporcionado con los archivos de personalización de este agente de IA. Alternativamente, crea la aplicación desde cero.

2. Si utilizas el archivo de manifiesto proporcionado, reemplaza los siguientes marcadores de posición con tus propios valores de configuración:

   Marcador de posición	Descripción
   {{Replace with Slack bot name}}	El nombre que deseas que tenga tu bot de Slack, tal como se muestra a los usuarios. Reemplaza este valor en dos lugares del manifiesto.
   {{Replace with Jitterbit API URL}}	La URL del servicio de la API personalizada de Jitterbit que creaste en Crear la API personalizada de Jitterbit.

3. Instala la aplicación en tu espacio de trabajo de Slack.

4. Obtén el token del bot (para el campo Token de OAuth de usuario del bot de la conexión de Slack) e ingresa su valor en la variable del proyecto slack_bot_oauth_user_token.

5. Configura la variable del proyecto slack_channel_name con el canal donde deben enviarse las notificaciones.

6. Ingresa el valor del token del bot en la variable del proyecto slack_bot_oauth_user_token y el nombre del canal en la variable del proyecto slack_channel_name. Configurarás estos en el siguiente paso.

Configurar una cuenta de servicio de Google y una unidad compartida

Esta configuración es obligatoria solo si utilizas el flujo de trabajo Data upload Utility - Google Drive to Azure Blob. Debes tener un proyecto activo de Google Cloud para continuar. Si no tienes uno, puedes crear uno siguiendo las instrucciones de Google.

Crear una cuenta de servicio de Google

Sigue los pasos a continuación para crear una clave de la cuenta de servicio de Google a fin de permitir que la utilidad acceda de forma segura a los archivos de tu Google Drive:

1. En la consola de Google Cloud, utiliza la barra de búsqueda para encontrar y navegar a la página Cuentas de servicio.

2. Si ya tienes una cuenta de servicio que deseas utilizar, ve al paso 3. De lo contrario, haz clic en Crear cuenta de servicio, proporciona un nombre y haz clic en Listo. No se necesitan permisos ni acceso adicionales.

   

3. Selecciona la cuenta de servicio para abrir sus Detalles de la cuenta de servicio:

   

4. Ve a la pestaña Claves y utiliza el menú Agregar clave para seleccionar Crear clave nueva.

   

5. Elige JSON como tipo de clave y haz clic en Crear. Se descargará en tu computadora un archivo JSON que contiene las credenciales.

6. Abre el archivo JSON descargado para encontrar los siguientes valores necesarios para configurar las variables del proyecto de Google Drive:

   • client_email: Este es el valor para la variable del proyecto Google_Client_Email y se necesita para configurar la unidad compartida de Google en la siguiente sección.
   • private_key: Este es el valor para la variable del proyecto Google_Private_Key.

7. Habilita la API de Google Drive en tu cuenta de Google Cloud:

   1. En la consola de Google Cloud, usa la barra de búsqueda para encontrar y navegar a la página de APIs y Servicios.

   2. Accede a la Biblioteca de APIs y selecciona la API de Google Drive:

      

   3. Haz clic en el botón Habilitar:

      

Configura la unidad compartida de Google

La unidad compartida de Google debe configurarse de la siguiente manera para permitir que la utilidad acceda a cualquier archivo que cargues en ella:

1. Crea una unidad compartida de Google si no tienes una.

2. Abre la unidad compartida y copia su ID desde la URL del navegador. El ID es la larga cadena de caracteres al final. Por ejemplo, si la URL es https://drive.google.com/drive/folders/dftg-LbGrP7hdfd, el ID es dftg-LbGrP7hdfd. Este ID es el valor de la variable de proyecto Google_Drive_ID al configurar variables de proyecto de Google Drive.

3. Haz clic en el nombre de la unidad compartida en la parte superior de la página y selecciona Administrar miembros. Aparece un diálogo.

4. En el campo Agregar personas y grupos, pega el valor de client_email del archivo JSON que descargaste anteriormente.

5. Asigna el rol de Gestor de contenido a la cuenta de servicio y confirma la acción.

Configura variables de proyecto

En el proyecto de Studio instalado anteriormente a través de Marketplace, debes establecer valores para las siguientes variables de proyecto.

Esto se puede hacer usando el menú de acciones del proyecto para seleccionar Variables de proyecto y abrir un panel en la parte inferior de la página donde puedas revisar y establecer los valores.

Salesforce

Jira

Confluence

Google Drive

Azure Blob Storage

Azure AI Search

Azure OpenAI

Slack

Común

Prueba las conexiones

Prueba las configuraciones del endpoint para verificar la conectividad usando los valores de variables de proyecto definidos.

Para probar las conexiones, ve a la pestaña Project endpoints and connectors (Endpoints de proyecto y conectores) de la paleta de componentes de diseño, coloca el cursor sobre cada endpoint y haz clic en Test (Prueba).

Implementa el proyecto

Implementa el proyecto de Studio.

Para implementar el proyecto, usa el menú de acciones del proyecto para seleccionar Deploy (Implementar).

Implementa el proyecto

Implementa el proyecto de Studio. Esto se puede hacer usando el menú de acciones del proyecto para seleccionar Deploy (Implementar).

Crear la API personalizada de Jitterbit

Crea una API personalizada usando API Manager para una de las siguientes opciones:

• Controlador de solicitudes de API de bot de Slack: Requerido si usas la notificación de Slack incluida en el diseño de este agente de IA.
• Controlador de solicitudes de API genérico: Opcional. Úsalo para manejar solicitudes de API desde cualquier aplicación.

Crear el controlador de solicitudes de API de bot de Slack

Esta API personalizada de Jitterbit activará la operación Slack Bot API Request Handler. Configura y publica la API personalizada con los siguientes parámetros:

• API Service: Slack Bot API Request Handler
• Path: /
• Project: Selecciona el proyecto de Studio creado a partir de Jitterbit Knowledge Agent en Marketplace
• Operation to Trigger: Slack Bot API Request Handler
• Method: POST
• Response Type: System Variable

Guarda la URL del servicio de la API publicada para usarla al crear la aplicación de Slack. Se puede encontrar la URL del servicio en el cajón de detalles de API en la pestaña Services pasando el cursor sobre la columna Actions del servicio y haciendo clic en Copy API service URL.

Controlador de solicitudes de API genérico

Esta API personalizada de Jitterbit activará la operación Generic API request Handler. No es obligatoria. Crea esta API si usas otras aplicaciones para procesar solicitudes de HTTP API. Configura y publica la API personalizada con los siguientes parámetros:

• Service name: Generic API request Handler
• Project: Selecciona el proyecto de Studio creado a partir de Jitterbit Knowledge Agent en Marketplace
• Operation: Generic API request Handler
• Method: POST
• Response type: System Variable

{
    "username": "johnr",
    "prompt": "How to connect to mysql using a connector?"
}

{
    "message": "To connect to a MySQL database using the Database connector, follow these steps:   - Use the MySQL JDBC driver that ships with the agent for additional features like manual queries.",
    "references": [],
    "status_code": 200
}

Revisar los flujos de trabajo del proyecto

En el proyecto de Studio abierto, revisa los flujos de trabajo junto con las descripciones que se presentan a continuación para entender qué hacen.

1. Data upload Utility - JIRA Ticket to Azure Index

   Este flujo de trabajo obtiene problemas de Jira y luego ejecuta el flujo de trabajo Utility - Azure Data Upload and Index para cargar problemas en Azure Blob Storage e indexarlos en el índice de Azure AI Search.

   La operación inicial es Main - JIRA tickets upload. Se obtienen los siguientes campos:

   "fields": [
       "summary",
       "status",
       "assignee",
       "description",
       "reporter",
       "created",
       "updated",
       "priority",
       "issuetype",
       "components",
       "comment"
    ]
   

   Este flujo de trabajo puede configurarse para obtener todos los problemas, o solo problemas nuevos y actualizados, usando las variables del proyecto Jira.

2. Data upload Utility - SF Cases to Azure Index

   Este flujo de trabajo recupera casos de soporte de Salesforce y luego ejecuta el flujo de trabajo Utility - Azure Data Upload and Index para cargar casos en Azure Blob Storage e indexarlos en el índice de Azure AI Search.

   La operación inicial es Main - SF Cases Upload.

   En la configuración de la actividad Salesforce Query, la siguiente consulta recupera información de casos de soporte por agente. Si tu organización de Salesforce no usa estos objetos y campos, o si la información de casos de soporte se almacena en objetos y campos diferentes, este flujo de trabajo no funcionará correctamente. Personaliza la consulta en este flujo de trabajo para que se alinee con el modelo de datos de tu organización de Salesforce:

SELECT Account.Name,
           Owner.Email,
           Owner.Name,
           (SELECT CreatedBy.Email,
                   CreatedBy.Name,
                   Id,
                   CommentBody,
                   CreatedDate,
                   LastModifiedDate,
                   LastModifiedBy.Email,
                   LastModifiedBy.Name
            FROM   CaseComments),
           Id,
           CaseNumber,
           CreatedDate,
           Description,
           LastModifiedDate,
           Origin,
           Priority,
           Reason,
           Status,
           Subject,
           Type,
           CreatedBy.Email,
           CreatedBy.Name,
           LastModifiedBy.Email,
           LastModifiedBy.Name
    FROM Case

Este flujo de trabajo se puede configurar para obtener todos los casos, o solo casos nuevos y actualizados, usando las variables del proyecto de Salesforce.

1. Data upload Utility - Confluence Pages to Azure Index

   Este flujo de trabajo recupera páginas de Confluence y luego ejecuta el flujo de trabajo Utility - Azure Data Upload and Index para cargar documentos en Azure Blob Storage e indexarlos en el índice de Azure AI Search.

   La operación inicial es Main - Load Confluence Pages.

   Este flujo de trabajo obtiene todas las páginas de Confluence en cada ejecución.

2. Data upload Utility - Google Drive to Azure Blob

   Este flujo de trabajo recupera archivos de Google Drive y luego ejecuta el flujo de trabajo Utility - Azure Data Upload and Index para indexarlos en el índice de Azure AI Search.

   La operación inicial es Main - Google Drive Upload.

   Los tipos de archivo compatibles incluyen Google Docs, Google Spreadsheets y los compatibles con la indexación de blobs de Azure Storage.

   Los tamaños máximos de archivo compatibles se enumeran como el tamaño máximo de blob en los límites del indexador de Azure AI Search para tu nivel de servicio de búsqueda de IA. Por ejemplo, para el nivel básico, el límite es 16 MB; para S1, el límite es 128 MB.

   Este flujo de trabajo se puede configurar para obtener todos los archivos, o solo archivos nuevos y actualizados, usando las variables del proyecto de Google Drive.

3. Utility - Azure Data Upload and Index

   Se trata de un flujo de trabajo de utilidad común utilizado por los flujos de trabajo Data upload Utility para cargar datos en Azure Blob Storage e indexarlos en Azure AI Search.

4. Main Entry - Slack API Request Handler

   Este flujo de trabajo gestiona solicitudes entrantes del bot de Slack. Se activa a través de una API personalizada de Jitterbit cada vez que tu equipo interactúa con la interfaz de usuario del chat del bot de Slack (es decir, envía un mensaje de Slack). La configuración de la API personalizada de Jitterbit se describe en Crear la API personalizada de Jitterbit más adelante en esta página.

   Si no estás usando Slack, se puede ignorar este flujo de trabajo y no se activará. Para usar una interfaz de chat diferente para que tu equipo interactúe, usa el flujo de trabajo Generic API Request Handler, también activado a través de una API personalizada de Jitterbit.

5. Generic API Request Handler

   Este flujo de trabajo procesa solicitudes de API HTTP de cualquier aplicación. Para integrar con tus aplicaciones, crea una API personalizada de Jitterbit que active la operación Generic API request Handler. La URL de esta API puede ser utilizada por cualquier aplicación para enviar y recibir solicitudes.

   La configuración de la API personalizada de Jitterbit se describe en Crear la API personalizada de Jitterbit más adelante en esta página.

Activar los flujos de trabajo del proyecto

Para la carga de datos inicial, ejecuta cualquiera o todos los flujos de trabajo Data upload Utility dependiendo de tus fuentes de datos. Esto se puede hacer usando la opción Run de la operación inicial que se muestra al pasar el cursor sobre la operación. Necesitarás ejecutar la operación nuevamente en el futuro si tus datos se actualizan.

Los otros dos flujos de trabajo principales se activan mediante las API personalizadas de Jitterbit:

• Main Entry - Slack API Request Handler: Este flujo de trabajo se activa desde Slack a través de la API personalizada Slack Bot API Request Handler. El envío de un mensaje directo a la aplicación de Slack iniciará la activación de la API personalizada.

• Generic API Request Handler: Este flujo de trabajo se activa desde otra aplicación a través de la API personalizada Generic API request Handler. El envío de una solicitud a la API configurada iniciará la activación de la API personalizada.

Todos los demás flujos de trabajo se activan mediante otras operaciones y son dependientes de los listados anteriormente. No se pretende que se ejecuten por sí solos.

Solución de problemas

Si encuentras problemas, revisa los siguientes registros para obtener información detallada sobre solución de problemas:

• Registros de API
• Registros de operación

Para obtener asistencia adicional, comunícate con el soporte de Jitterbit.