GPT

Este documento detalla el flujo de trabajo para integrar un asistente de OpenAI con sistemas externos, gestionando conversaciones y automatizando acciones mediante herramientas personalizadas.

Resumen Funcional

Este flujo de trabajo está diseñado para manejar interacciones complejas entre un asistente de OpenAI y un sistema externo, con el objetivo de procesar y gestionar mensajes de usuario, realizar llamadas a herramientas externas, y devolver respuestas en un contexto de conversación continuo.

1. Inicio del Proceso: El flujo comienza con la verificación de la existencia de un hilo de conversación previo. Si se encuentra un hilo existente, se reutiliza; de lo contrario, se crea uno nuevo para mantener la coherencia de la conversación.

2. Envío del Mensaje del Usuario: Una vez establecido el hilo, el mensaje del usuario se envía a OpenAI a través de la API, permitiendo que el asistente lo procese en el contexto del hilo activo.

3. Creación de una Ejecución: Se crea una "ejecución" (run) dentro del hilo, lo que permite al asistente procesar el mensaje del usuario y llevar a cabo las acciones necesarias según el flujo de trabajo configurado.

4. Sondeo de Cambios de Estado: El sistema realiza un sondeo continuo para monitorear el estado de la ejecución hasta que se complete o se requiera una acción adicional.

5. Enrutamiento de Herramientas: Si la ejecución requiere acciones adicionales, como consultas a APIs externas (para obtener información del cliente, departamentos, temas, o crear tickets), estas herramientas se llaman y sus resultados se integran en la conversación.

6. Recuperación del Último Mensaje: Una vez que la ejecución se ha completado, se recupera el último mensaje generado por OpenAI para ser utilizado en la respuesta final al usuario.

7. Finalización: El proceso culmina con la presentación de la respuesta final al usuario, cerrando así el ciclo de la conversación.

Este flujo de trabajo está diseñado para ser robusto y modular, permitiendo la integración de diversas funcionalidades externas mediante herramientas personalizadas, mientras mantiene la coherencia en las interacciones del asistente de OpenAI dentro de un hilo de conversación continuo.

Paso 1: Búsqueda del hilo existente para la conversación

/* 
Checks if we can find an existing (assistant) thread for this conversation
*/

// Busca registros en la tabla 'ThreadsTable' que coincidan con el 'conversationId' del evento.
const threadIds = await ThreadsTable.findRecords({
    filter: { conversationId: event.conversationId }, // Filtra los registros por 'conversationId'.
    limit: 1 // Limita los resultados a 1, obteniendo solo el primer hilo coincidente.
});

// Asigna el ID del hilo encontrado a 'workflow.thread_id', si existe un hilo coincidente.
workflow.thread_id = threadIds[0]?.threadId

Este fragmento de código se encarga de buscar un hilo de conversación existente en la base de datos asociado al conversationId del evento actual.

1. Búsqueda en la tabla: Utiliza la tabla ThreadsTable para buscar registros que tengan un conversationId que coincida con el del evento. Se utiliza un filtro para esta búsqueda y se limita el resultado a un solo registro.

2. Asignación del ID del hilo: Si se encuentra un hilo correspondiente, se asigna su threadId a la variable workflow.thread_id. Si no se encuentra ningún hilo (por ejemplo, si es la primera vez que se procesa esta conversación), workflow.thread_id quedará indefinido.

Este proceso es crucial para mantener la continuidad en las conversaciones, permitiendo que el asistente interactúe de manera coherente dentro de un mismo hilo o conversación.

Paso 2: Crear thread si no se encuentra en la tabla

/* 
Creates a new thread if one wasn't found in the table
*/

// Paso 1: Verificación de la existencia de un hilo
if (!workflow.thread_id) {
  // Paso 2: Preparación de datos y configuración para la solicitud de creación de hilo
  let data = JSON.stringify({})

  let config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://api.openai.com/v1/threads',
    headers: {
      'OpenAI-Beta': 'assistants=v2',
      Authorization: 'Bearer ' + env.OPENAI_KEY,
      'Content-Type': 'application/json'
    },
    data: data
  }

  // Paso 3: Envío de la solicitud para crear un nuevo hilo
  const response = await axios.request(config)

  // Paso 4: Almacenamiento del ID del nuevo hilo en 'workflow.thread_id'
  workflow.thread_id = response.data.id

  // Paso 5: Creación de un nuevo registro en la tabla con el ID del hilo y el ID de la conversación
  await ThreadsTable.createRecord({
    threadId: workflow.thread_id,
    conversationId: event.conversationId
  })
}

Este fragmento de código maneja la creación de un nuevo hilo de conversación en caso de que no se haya encontrado uno existente.

1. Verificación de la existencia de un hilo: Se comprueba si workflow.thread_id es nulo o indefinido, lo que indicaría que no se encontró un hilo existente.

2. Preparación de datos y configuración para la solicitud de creación de hilo: Se preparan los datos y la configuración necesarios para realizar una solicitud HTTP POST a la API de OpenAI para crear un nuevo hilo.

3. Envío de la solicitud para crear un nuevo hilo: Se realiza la solicitud HTTP mediante axios para crear el nuevo hilo en la API de OpenAI.

4. Almacenamiento del ID del nuevo hilo en workflow.thread_id: Una vez creada, el ID del nuevo hilo se guarda en la variable workflow.thread_id para futuras referencias.

5. Creación de un nuevo registro en la tabla: Finalmente, se guarda un nuevo registro en la tabla ThreadsTable, asociando el ID del hilo recién creado con el conversationId del evento, asegurando la persistencia de la conversación.

Paso 3: Enviar el Mensaje del Usuario al Hilo en la API de OpenAI

/*
Posts the user's message into the thread
*/

// Prepara los datos del mensaje del usuario, incluyendo el rol 'user' y el contenido del mensaje.
let data = JSON.stringify({
  role: 'user', // Indica que el mensaje es enviado por el usuario.
  content: event.preview // Contenido del mensaje del usuario.
});

// Configura la solicitud HTTP POST para enviar el mensaje al hilo correspondiente en la API de OpenAI.
let config = {
  method: 'post',
  maxBodyLength: Infinity, // Permite el tamaño máximo posible para el cuerpo de la solicitud.
  url: `https://api.openai.com/v1/threads/${workflow.thread_id}/messages`, // URL de la API con el ID del hilo.
  headers: {
    'OpenAI-Beta': 'assistants=v2', // Especifica la versión del asistente en la API.
    Authorization: `Bearer ${env.OPENAI_KEY}`, // Autenticación mediante la clave de la API.
    'Content-Type': 'application/json' // Especifica el tipo de contenido como JSON.
  },
  data: data // Datos a enviar en la solicitud.
};

// Envía la solicitud HTTP para postear el mensaje del usuario en el hilo.
await axios.request(config);

Este código realiza el envío del mensaje del usuario al hilo correspondiente en la API de OpenAI. A través de una solicitud HTTP POST, se asegura de que el contenido del mensaje del usuario se añada al hilo identificado por workflow.thread_id. Esto permite que la conversación con el asistente se mantenga dentro del mismo contexto, facilitando respuestas coherentes y relevantes por parte del asistente.

Paso 4: Crear una Ejecución para un Asistente de OpenAI Usando Axios

/* Create a run */

// Inicializa la acción requerida en el flujo de trabajo como un objeto vacío.
workflow.required_action = {};

// Realiza una solicitud HTTP POST para crear una ejecución (run) en el hilo correspondiente.
const creationResponse = await axios.request({
  method: 'post',
  maxBodyLength: Infinity, // Permite el tamaño máximo posible para el cuerpo de la solicitud.
  url: `https://api.openai.com/v1/threads/${workflow.thread_id}/runs`, // URL de la API con el ID del hilo.
  headers: {
    'OpenAI-Beta': 'assistants=v2', // Especifica la versión del asistente en la API.
    Authorization: `Bearer ${env.OPENAI_KEY}`, // Autenticación mediante la clave de la API.
    'Content-Type': 'application/json' // Especifica el tipo de contenido como JSON.
  },
  data: JSON.stringify({
    assistant_id: env.ASSISTANT_ID // Asigna el ID del asistente que realizará la ejecución.
  })
});

// Extrae el ID de la ejecución creada desde la respuesta de la API.
const runId = creationResponse.data.id;

// Asigna el ID de la ejecución al flujo de trabajo para su uso posterior.
workflow.run_id = runId;

Este código crea una "ejecución" (run) en el contexto de un hilo existente usando la API de OpenAI.

1. Inicialización: Se establece workflow.required_action como un objeto vacío, preparando el flujo de trabajo para recibir nuevas acciones.

2. Creación de la ejecución: Se realiza una solicitud HTTP POST a la API de OpenAI para crear una nueva ejecución dentro del hilo identificado por workflow.thread_id. La solicitud incluye el assistant_id, que identifica al asistente específico que va a ejecutar la acción.

3. Asignación del ID de la ejecución: El ID de la nueva ejecución, que se recibe en la respuesta de la API, se asigna a workflow.run_id, permitiendo que el flujo de trabajo siga manejando esta ejecución en los siguientes pasos.

Esta ejecución es esencial para permitir que el asistente de OpenAI procese y responda en el contexto del hilo de conversación actual.

Paso 5: Sondeo para Cambios de Estado y Determinación del Siguiente Paso

Esta execución debe ir en un nodo propio.

/* Poll for status changes and determine next step */

// Define una función asíncrona que realiza el sondeo del estado de la ejecución hasta que se complete.
const waitTillRunComplete = async () => {
  let isComplete = false; // Inicializa la variable para rastrear si la ejecución se ha completado.

  while (!isComplete) {
    // Realiza una solicitud GET para obtener el estado actual de la ejecución.
    const statusResponse = await axios.get(`https://api.openai.com/v1/threads/${workflow.thread_id}/runs/${workflow.run_id}`, {
      headers: {
        'OpenAI-Beta': 'assistants=v2', // Especifica la versión del asistente en la API.
        Authorization: `Bearer ${env.OPENAI_KEY}`, // Autenticación mediante la clave de la API.
        'Content-Type': 'application/json' // Especifica el tipo de contenido como JSON.
      },
      maxBodyLength: Infinity // Permite el tamaño máximo posible para el cuerpo de la solicitud.
    });

    // Desestructura el estado y la acción requerida desde la respuesta.
    const { status, required_action } = statusResponse.data;

    // Muestra el estado actual de la ejecución en la consola.
    console.log('The run status is:', status);

    // Verifica si el estado es 'queued' o 'in_progress'.
    if (['queued', 'in_progress'].includes(status)) {
      // Espera 1500ms antes de realizar la siguiente verificación.
      await new Promise(resolve => setTimeout(resolve, 1500));
    } else {
      // Si la ejecución requiere una acción, se guarda en el flujo de trabajo.
      if (status === 'requires_action') {
        workflow.required_action = required_action;
      } else {
        workflow.required_action = null; // Si no requiere acción, se limpia la acción requerida.
      }
      
      isComplete = true; // Marca la ejecución como completada.
    }
  }
};

// Llama a la función para esperar hasta que la ejecución se complete.
await waitTillRunComplete()

Este paso implementa un sondeo continuo para verificar el estado de la ejecución (run) hasta que esta se complete o requiera una acción.

1. Definición de la función asíncrona: La función waitTillRunComplete realiza sondeos periódicos para obtener el estado actual de la ejecución asociada al hilo.

2. Sondeo del estado: Dentro de un bucle while, se envía una solicitud HTTP GET para verificar el estado actual de la ejecución. Dependiendo del estado (queued, in_progress, requires_action, etc.), se decide si continuar esperando o terminar el sondeo.

3. Manejo de la respuesta: Si el estado es queued o in_progress, la función espera 1500 milisegundos antes de realizar otra verificación. Si el estado es requires_action, se guarda la acción requerida en workflow.required_action. Si no se requiere acción, se limpia esta variable.

4. Finalización del sondeo: El bucle se detiene una vez que la ejecución ya no está en progreso, y se ha determinado si requiere una acción o si se ha completado.

Este proceso es fundamental para sincronizar el flujo de trabajo con el estado de la ejecución, permitiendo tomar decisiones basadas en el estado actual del proceso en OpenAI.

Paso 6: Herramienta de Enrutamiento

Este paso permite que el asistente maneje interacciones complejas con APIs externas, facilitando la automatización de procesos como la creación de tickets o la recuperación de datos de clientes. Este ejemplo tiene varios llamados propios de nuestra solución.

// Obtener cliente por número de cliente
async function get_client({ param, client_id }) {
  const response = await axios.get(
    `https://amecom2.suricata2.com.ar/api/ws?token=elcris&${param}=${client_id}`
  );
  return response.data; // Retorna los datos del cliente obtenidos de la API.
}

// Obtener Departamentos
async function get_departments({ merchant, cloudtoken }) {
  const response = await axios.get(
    `https://suricata1.com.ar/api/areas?merchant=${merchant}&token=${cloudtoken}`
  );
  return response.data; // Retorna la lista de departamentos obtenidos de la API.
}

// Obtener Temas
async function get_topics({ merchant , id_department, cloudtoken }) {
  const response = await axios.get(
    `https://suricata1.com.ar/api/topics?merchant=${merchant}&depto=${id_department}&token=${cloudtoken}`
  );
  return response.data; // Retorna la lista de temas obtenidos de la API.
}

// Crear Ticket
async function createTicket({ merchant, client_id, e_mail, id_department, topic_id, a_status, s_status, debt, address, idcustomer, node, ip, first_name }) {
  const url = `https://${merchant}.suricata.cloud/api/creartickessienna`; 
  const payload = {
    cel: client_id, // Número de teléfono del cliente.
    email: e_mail, // Correo electrónico del cliente.
    token: "2233344", // Token de autenticación.
    siennadepto: id_department, // ID del departamento relacionado con el ticket.
    siennatopic: topic_id, // ID del tema relacionado con el ticket.
    siennasource: "8", // Fuente del ticket.
    nya: first_name, // Nombre del cliente.
    conversation_url: " ",  // Revisar si se espera un valor aquí.
    conversation_id: "link", // ID de la conversación.
    siennaestado: "1",  // Estado del ticket en Cloud 1-Abierto.
    a_status: a_status, // Estado adicional del ticket.
    s_status: s_status, // Otro estado adicional del ticket.
    deuda: debt, // Deuda del cliente, si aplica.
    address: address, // Dirección del cliente.
    cliente: idcustomer,  // ID del cliente.
    nodo: node, // Nodo de red asociado al cliente.
    ip: ip // Dirección IP del cliente.
  };

  try {
    const response = await axios.post(url, payload);
    return response.data; // Retorna los datos de la respuesta al crear el ticket.
  } catch (error) {
    console.error('Error creating ticket:', error);
    throw error; // Lanza el error para ser manejado por el llamador.
  }
}

// Registro de herramientas disponibles para su uso
const registeredTools = {
  'get_client': get_client, // Herramienta para obtener información del cliente.
  'get_departments': get_departments, // Herramienta para obtener departamentos.
  'get_topics': get_topics, // Herramienta para obtener temas.
  'createTicket': createTicket, // Herramienta para crear un ticket.
}

/**
 * Analiza los argumentos de una llamada a herramienta.
 * @param {Object} toolCall - Objeto que contiene la información de la llamada a la herramienta.
 * @returns {Object} - Argumentos analizados de la llamada a la herramienta.
 */
function parseArguments(toolCall) {
  return JSON.parse(toolCall.function.arguments); // Parsea los argumentos desde la llamada a la herramienta.
}

/**
 * Formatea la salida de la herramienta para OpenAI.
 * @param {string} toolCallId - El ID de la llamada a la herramienta.
 * @param {any} output - Los datos de salida a formatear.
 * @returns {Object} - Salida de la herramienta formateada.
 */
function formatToolOutput(toolCallId, output) {
  return {
    tool_call_id: toolCallId, // ID de la llamada a la herramienta.
    output: JSON.stringify(output) // Salida formateada como una cadena JSON.
  };
}

/**
 * Maneja múltiples llamadas a herramientas de forma asíncrona.
 * @param {Object[]} toolCalls - Array de objetos de llamadas a herramientas.
 * @returns {Promise<Object[]>} - Promesa que se resuelve en un array de salidas de herramientas formateadas.
 */
async function handleToolCalls(toolCalls) {
  return Promise.all(
    toolCalls.map(async (toolCall) => {
      const toolName = toolCall.function.name; // Nombre de la herramienta llamada.
      const toolFunction = registeredTools[toolName]; // Función de la herramienta registrada.

      if (!toolFunction) {
         throw new ReferenceError(`Tool ${toolName} is not implemented`); // Error si la herramienta no está implementada.
      }

      const args = parseArguments(toolCall); // Parsear los argumentos de la llamada a la herramienta.
      const output = await toolFunction(args); // Ejecutar la herramienta con los argumentos.

      console.log(`Called the "${toolName}" tool. Output was:`, output);

      return formatToolOutput(toolCall.id, output); // Formatear y retornar la salida de la herramienta.
    })
  );
}

/**
 * Envía las salidas de herramientas a la API de OpenAI.
 * @param {string} threadId - El ID del hilo.
 * @param {string} runId - El ID de la ejecución.
 * @param {string} openai_key - La clave API de OpenAI.
 * @param {Object[]} toolOutputs - Array de salidas de herramientas formateadas.
 * @returns {Promise<void>} - Promesa que se resuelve cuando las salidas de herramientas se envían correctamente.
 */
async function submitToolOutputs(threadId, runId, openai_key, toolOutputs) {
  try {
    const response = await axios.request({
      method: 'post',
      url: `https://api.openai.com/v1/threads/${threadId}/runs/${runId}/submit_tool_outputs`, // URL de la API con los IDs de hilo y ejecución.
      headers: {
        'Content-Type': 'application/json', // Especifica el tipo de contenido como JSON.
        Authorization: `Bearer ${openai_key}`, // Autenticación mediante la clave de la API.
        'OpenAI-Beta': 'assistants=v2' // Especifica la versión del asistente en la API.
      },
      data: { tool_outputs: toolOutputs }, // Datos que contienen las salidas de las herramientas.
      maxBodyLength: Infinity // Permite el tamaño máximo posible para el cuerpo de la solicitud.
    });

    console.log('Tool output submission response:', response.data);
  } catch (error) {
    console.error('Error submitting tool outputs:', error); // Manejo de errores en el envío de salidas.
  }
}

/**
 * Prepara y envía las salidas de herramientas.
 * Obtiene las llamadas a herramientas, las maneja y envía las salidas a la API de OpenAI.
 * @returns {Promise<void>} - Promesa que se resuelve cuando las salidas de herramientas están preparadas y enviadas.
 */
async function prepareAndSubmitOutputs() {
  // Ejemplo de obtención y preparación de datos
  const toolCalls = workflow.required_action.submit_tool_outputs.tool_calls; // Obtiene las llamadas a herramientas requeridas.
  const toolOutputs = await handleToolCalls(toolCalls); // Maneja las llamadas y obtiene las salidas.
  await submitToolOutputs(workflow.thread_id, workflow.run_id, env.OPENAI_KEY, toolOutputs); // Envía las salidas a la API de OpenAI.
}

await prepareAndSubmitOutputs(); // Llama a la función para preparar y enviar las salidas.

Este paso implementa una herramienta de enrutamiento que maneja diversas llamadas a funciones API relacionadas con clientes, departamentos, temas, y creación de tickets. Además, se encarga de gestionar las llamadas a estas funciones, formatear los resultados y enviarlos a la API de OpenAI.

1. Definición de Funciones de Herramientas: Varias funciones (get_client, get_departments, get_topics, createTicket) interactúan con APIs externas para obtener información o realizar acciones específicas, como la creación de un ticket.

2. Registro de Herramientas: Se registra un conjunto de herramientas en el objeto registeredTools para que puedan ser llamadas dinámicamente.

3. Manejo de Llamadas a Herramientas: La función handleToolCalls procesa cada llamada a herramienta, ejecuta la función correspondiente y formatea la salida.

4. Envío de Salidas a la API de OpenAI: Las salidas de las herramientas formateadas se envían a OpenAI para ser utilizadas en el contexto del asistente.

Paso 7: Recuperar el Último Mensaje desde la API de OpenAI

/*
Run has now completed, so get the newest message
*/

// Realiza una solicitud GET para recuperar los mensajes más recientes del hilo en la API de OpenAI.
const response = await axios.request({
  method: 'get',
  maxBodyLength: Infinity, // Permite el tamaño máximo posible para el cuerpo de la solicitud.
  url: `https://api.openai.com/v1/threads/${workflow.thread_id}/messages`, // URL de la API con el ID del hilo.
  headers: {
    'OpenAI-Beta': 'assistants=v2', // Especifica la versión del asistente en la API.
    Authorization: `Bearer ${env.OPENAI_KEY}`, // Autenticación mediante la clave de la API.
    'Content-Type': 'application/json' // Especifica el tipo de contenido como JSON.
});

// Extrae el contenido del último mensaje recibido y lo guarda en 'workflow.response'.
workflow.response = response.data.data[0].content[0].text.value;

Este paso se encarga de recuperar el último mensaje generado por el asistente de OpenAI después de que la ejecución haya finalizado.

1. Solicitud GET para recuperar mensajes: Se realiza una solicitud HTTP GET para obtener todos los mensajes asociados al hilo (workflow.thread_id). La API devuelve un array con los mensajes, de los cuales se extraerá el más reciente.

2. Extracción del contenido del mensaje: El contenido del último mensaje (más reciente) se extrae del array de datos que devuelve la API. Este contenido se guarda en la variable workflow.response para su uso posterior en el flujo de trabajo.

Este paso es crucial para obtener la respuesta final generada por el asistente en el contexto del hilo de conversación, lo que permite que la respuesta sea utilizada o presentada al usuario en la siguiente etapa del flujo de trabajo.