Migración de una aplicación Node.js con el SDK de OpenAI: Base URL, streaming y triaje con intervención humana

Migrar una aplicación Node.js en producción desde los endpoints directos de OpenAI hacia un proxy o pasarela unificada compatible no requiere reescribir la lógica principal del sistema. Gracias a que la librería oficial openai para Node.js expone configuraciones a nivel de cliente para modificar los orígenes de red y los encabezados, es posible redirigir el tráfico, auditar el consumo y aprovechar rutas alternativas sin sustituir el SDK.

Sin embargo, canalizar peticiones a través de una pasarela introduce ciertos factores operativos: administrar cabeceras de autenticación, procesar eventos de streaming sobre HTTP, diagnosticar errores en el perímetro y garantizar que las respuestas autónomas permanezcan bajo supervisión humana. En el triaje de atención al cliente —donde un modelo clasifica incidencias entrantes, redacta respuestas preliminares y propone acciones sobre los tickets—, validar las operaciones críticas mediante revisión humana resulta indispensable.

Esta guía muestra cómo reconfigurar el SDK de OpenAI en Node.js para trabajar con una pasarela compatible con OpenAI como OneMux, procesar propuestas de triaje en streaming e incorporar un control de aprobación humana antes de ejecutar acciones de alto impacto.

---

Arquitectura: triaje de soporte con aprobación humana

El triaje automatizado de soporte técnico implica procesar un ticket entrante, evaluar el sentimiento del usuario, clasificar la urgencia y proponer los siguientes pasos (como redactar una respuesta, añadir etiquetas o emitir una compensación parcial). Como se describe en la OpenAI Agents Guide, las arquitecturas de agentes que generan efectos secundarios en el mundo real se benefician de mantener el ciclo de orquestación dentro del código de la aplicación, donde se pueden aplicar salvaguardas y puntos de control de aprobación.

En lugar de conceder al modelo permisos de ejecución directa, la canalización de triaje se divide en dos fases bien diferenciadas:

1. Análisis y propuesta (ejecución del modelo): El modelo procesa el mensaje del usuario, emite en streaming su razonamiento interno junto con un borrador de respuesta y genera una llamada estructurada a herramientas (tool call) con las acciones recomendadas.
2. Aprobación y despacho (ejecución de la aplicación): La aplicación detiene el flujo de trabajo, almacena la propuesta en una cola de revisión y aguarda la confirmación de un agente humano antes de actualizar el estado del ticket o contactar al cliente.

Incoming Ticket ──> Node.js Service ──> OneMux Gateway ──> Model Inference
                                                                 │
                                                                 ▼
Ticket Updated  <── Support Agent  <── Review Queue  <── Proposed Actions
   (Execution)        (Approves)       (Intercepted)       & Draft Stream

---

Configuración del SDK de Node.js: Base URL y autenticación

El paquete oficial de npm openai permite redirigir las solicitudes a cualquier endpoint compatible modificando la propiedad baseURL. Puedes explorar los modelos disponibles en el catálogo de modelos de OneMux para seleccionar el modelo de completado idóneo.

En primer lugar, instala el paquete oficial:

npm install openai

Para apuntar a OneMux, inicializa la instancia del cliente con tu API key de OneMux y la URL base https://api.onemux.net/v1:

import OpenAI from 'openai';

// Initialize the OpenAI client pointing to the OneMux gateway
const client = new OpenAI({
  apiKey: process.env.ONEMUX_API_KEY,
  baseURL: 'https://api.onemux.net/v1',
});

Verificación de la autenticación

Al enrutar el tráfico mediante una pasarela, los patrones de fallo en la autenticación presentan matices concretos. Si la clave de API no se envía, no es válida o la cuenta no dispone de saldo suficiente en la plataforma, el cliente capturará un error AuthenticationError (HTTP 401). Antes de desplegar procesos de triaje en entornos de producción, comprueba tus credenciales consultando la guía de inicio rápido de OneMux.

---

Implementación de streaming para la redacción de triaje en tiempo real

Los agentes de soporte obtienen una mejor experiencia cuando visualizan los borradores de triaje conforme se generan, en lugar de esperar a que se resuelva la carga útil completa. Al invocar chat.completions.create con el parámetro stream: true, el SDK devuelve un flujo iterable asíncrono compuesto por Server-Sent Events (SSE).

La siguiente implementación envía el borrador de respuesta a la salida estándar (o al panel interno del agente) en streaming mientras captura las llamadas estructuradas a herramientas para la categorización del triaje:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ONEMUX_API_KEY,
  baseURL: 'https://api.onemux.net/v1',
});

interface TriageProposal {
  draftResponse: string;
  category?: string;
  priority?: 'low' | 'medium' | 'high' | 'urgent';
  suggestedRefundAmount?: number;
}

export async function triageTicketStream(
  ticketId: string,
  customerMessage: string
): Promise<TriageProposal> {
  const tools: OpenAI.ChatCompletionTool[] = [
    {
      type: 'function',
      function: {
        name: 'propose_ticket_action',
        description: 'Propose triage tags, priority updates, or billing adjustments.',
        parameters: {
          type: 'object',
          properties: {
            category: {
              type: 'string',
              enum: ['billing', 'technical_bug', 'account_access', 'general'],
            },
            priority: {
              type: 'string',
              enum: ['low', 'medium', 'high', 'urgent'],
            },
            suggestedRefundAmount: {
              type: 'number',
              description: 'Refund amount in USD if the user experienced downtime.',
            },
          },
          required: ['category', 'priority'],
        },
      },
    },
  ];

  const stream = await client.chat.completions.create({
    model: 'gpt-4o',
    stream: true,
    tools,
    messages: [
      {
        role: 'system',
        content:
          'You are a support triage assistant. Analyze the ticket, stream a helpful draft reply for the customer, and call propose_ticket_action with triage metadata.',
      },
      {
        role: 'user',
        content: customerMessage,
      },
    ],
  });

  let draftResponse = '';
  let toolCallArguments = '';
  let toolName = '';

  for await (const chunk of stream) {
    const delta = chunk.choices[0]?.delta;

    // Stream conversational draft chunks
    if (delta?.content) {
      draftResponse += delta.content;
      process.stdout.write(delta.content);
    }

    // Accumulate tool call chunks
    if (delta?.tool_calls) {
      for (const toolCall of delta.tool_calls) {
        if (toolCall.function?.name) {
          toolName = toolCall.function.name;
        }
        if (toolCall.function?.arguments) {
          toolCallArguments += toolCall.function.arguments;
        }
      }
    }
  }

  let parsedAction = {};
  if (toolName === 'propose_ticket_action' && toolCallArguments) {
    try {
      parsedAction = JSON.parse(toolCallArguments);
    } catch (err) {
      console.error('Failed to parse tool call JSON payload:', err);
    }
  }

  return {
    draftResponse,
    ...parsedAction,
  };
}

---

La barrera de aprobación humana

Permitir la ejecución autónoma de llamadas a herramientas puede provocar reembolsos indebidos o escalados de prioridad injustificados. La aplicación debe almacenar el objeto TriageProposal generado en un estado intermedio —por ejemplo, un registro en base de datos con el estado PENDING_APPROVAL— en lugar de ejecutar las acciones inmediatamente.

interface PendingReviewTicket {
  ticketId: string;
  status: 'PENDING_APPROVAL' | 'APPROVED' | 'REJECTED';
  proposal: TriageProposal;
}

// Step 1: Queue the proposal for human verification
async function queueForHumanReview(ticketId: string, proposal: TriageProposal) {
  console.log(`[Review Queue] Storing proposal for ticket ${ticketId}:`, proposal);
  // Persistence logic: await db.triageReviews.create({ ticketId, proposal, status: 'PENDING_APPROVAL' });
}

// Step 2: Human operator action handler
async function handleHumanDecision(
  reviewId: string,
  decision: 'APPROVE' | 'REJECT',
  modifiedProposal?: Partial<TriageProposal>
) {
  if (decision === 'REJECT') {
    console.log(`Review ${reviewId} rejected by operator.`);
    return;
  }

  // Execute business logic only after approval
  console.log(`Review ${reviewId} approved. Executing refund and priority assignment...`);
  // e.g., await paymentGateway.issueRefund(modifiedProposal.suggestedRefundAmount);
}

Esta separación asegura que, incluso si el modelo clasifica erróneamente una consulta rutinaria como urgente o sugiere una compensación no aplicable, un operador humano validará la acción antes de su ejecución.

---

Diagnóstico de errores: diferenciación entre errores del cliente, la pasarela y el proveedor ascendente

Al utilizar una pasarela compatible con OpenAI como OneMux, los incidentes pueden tener tres orígenes distintos: el código local de la aplicación, el proxy de la pasarela o el proveedor del modelo subyacente. Inspeccionar la instancia estándar APIError del SDK de openai permite aislar la causa raíz con precisión:

import OpenAI from 'openai';

try {
  await triageTicketStream('ticket-101', 'System is down since morning!');
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error(`Status Code: ${error.status}`);
    console.error(`Error Message: ${error.message}`);
    console.error(`Error Code: ${error.code}`);
    console.error(`Error Type: ${error.type}`);

    switch (error.status) {
      case 401:
        console.error('Check your OneMux API key in environment variables.');
        break;
      case 402:
        console.error('Account balance exhausted. Top up credits in the dashboard.');
        break;
      case 429:
        console.error('Rate limit reached or concurrent request ceiling exceeded.');
        break;
      case 502:
      case 504:
        console.error('Upstream model provider timeout or network disruption via gateway.');
        break;
      default:
        console.error('Unhandled API exception.');
    }
  } else {
    console.error('Non-API runtime error:', error);
  }
}

Desglose de códigos de estado comunes

---

Limitaciones y parámetros no probados

Aunque OneMux ofrece compatibilidad directa con los endpoints estándar de chat completions de OpenAI (/v1/chat/completions), conviene considerar las siguientes limitaciones:

1. Endpoints beta avanzados: Las funciones fuera de chat, embeddings y completions convencionales —como entornos sandbox alojados específicos o primitivas del runtime de asistentes administrados descritas en la documentación de OpenAI— requieren soporte explícito por parte de la pasarela. Comprueba la disponibilidad del endpoint en la documentación de la pasarela antes de desplegar.
2. Paso de cabeceras personalizadas: Los encabezados personalizados de organización o proyecto (OpenAI-Organization, OpenAI-Project) pueden ser ignorados o interpretados de forma distinta por las capas intermedias de proxy. Asegúrate de transmitir el token de autenticación mediante el esquema estándar Bearer.
3. Gestión del estado: Si planeas migrar desde la API administrada de OpenAI Assistants hacia un bucle de agentes controlado por la aplicación, tu servicio en Node.js deberá encargarse del almacenamiento y la persistencia del historial de las sesiones.

---

Conclusión

Migrar una aplicación Node.js basada en el SDK de OpenAI a una pasarela compatible implica un esfuerzo mínimo: actualiza el parámetro baseURL, proporciona la clave de API correspondiente de la pasarela y adapta el registro de errores para procesar los códigos de estado propios del servicio intermedio. Al desacoplar las propuestas generadas por el modelo de los efectos secundarios reales mediante una barrera de aprobación, tu sistema de triaje de atención al cliente conservará su agilidad operativa minimizando el riesgo de acciones no deseadas.

---

Fuentes

• OpenAI Agents Guide: https://developers.openai.com/api/docs/guides/agents
• OneMux Developer Documentation: https://onemux.net/docs