@hemia-ai/support-agents

Pack reutilizable de Hemia para flujos de atención al cliente y soporte.

Este paquete provee definiciones de agentes, definiciones de tools, contratos TypeScript y JSON Schemas para FAQs, triage, troubleshooting, tickets, escalamiento, satisfacción y revisión de calidad.

No incluye un runtime independiente. Se acopla a los paquetes base de Hemia:

• @hemia-ai/agents-core para contratos de agentes y tools.
• @hemia-ai/agents-runtime para registro y ejecución.
• @hemia-ai/agents-tools para registro y handlers de tools.

Instalación

pnpm add @hemia-ai/support-agents

Uso dentro del workspace:

pnpm add @hemia-ai/support-agents --workspace

Inicio Rápido

import { HemiaAgentRuntime } from '@hemia-ai/agents-runtime';
import { InMemoryToolRegistry } from '@hemia-ai/agents-tools';
import {
  SUPPORT_AGENT_KEYS,
  registerSupportAgents,
  registerSupportTools,
} from '@hemia-ai/support-agents';

const runtime = new HemiaAgentRuntime({ services });
const toolRegistry = new InMemoryToolRegistry();

registerSupportAgents(runtime);
registerSupportTools(toolRegistry);

const result = await runtime.runAgent({
  agentKey: SUPPORT_AGENT_KEYS.triage,
  payload: {
    message: 'No me llegan los mensajes de WhatsApp desde ayer.',
    module: 'channels',
  },
  context: {
    tenantId: 'tenant_123',
    conversationId: 'conv_456',
    channel: 'whatsapp',
    locale: 'es-MX',
  },
});

Agentes

| Agent key | Export | Propósito | |---|---|---| | support.faq | FaqAgent | Responder FAQs de soporte con conocimiento confiable. | | support.triage | SupportTriageAgent | Clasificar categoría, severidad, módulo afectado y prioridad. | | support.troubleshooting | TroubleshootingAgent | Guiar diagnóstico y sugerir soluciones seguras. | | support.ticket | TicketAgent | Crear, actualizar, cerrar o consultar tickets de soporte. | | support.escalation | EscalationAgent | Escalar casos no resueltos o riesgosos a canales humanos. | | support.customer_satisfaction | CustomerSatisfactionAgent | Evaluar satisfacción después de interacciones de soporte. | | support.quality_review | QualityReviewAgent | Revisar calidad de respuestas y cumplimiento de políticas. |

Las keys support.* son contratos estables para registro en runtime, policies, tracing y composición con productos.

Tools

| Tool name | Alias | Propósito | |---|---|---| | support.search_faq | searchFaqTool | Buscar respuestas en FAQs. | | support.create_ticket | createTicketTool | Crear un ticket de soporte. | | support.update_ticket | updateTicketTool | Actualizar estado, prioridad, categoría o notas. | | support.get_ticket_status | getTicketStatusTool | Consultar estado de un ticket. | | support.collect_diagnostic_info | collectDiagnosticInfoTool | Recopilar información de diagnóstico. | | support.escalate_to_human | escalateToHumanTool | Escalar un caso a soporte humano. |

Los handlers de tools son específicos de cada producto. Loop, Directory, soporte interno o un helpdesk externo deben conectar estos contratos a sus propios sistemas.

API

Exports principales:

import {
  SUPPORT_AGENT_KEYS,
  SUPPORT_TOOL_NAMES,
  supportAgentDefinitions,
  supportToolDefinitions,
  registerSupportAgents,
  registerSupportTools,
  FaqAgent,
  SupportTriageAgent,
  TroubleshootingAgent,
  TicketAgent,
  EscalationAgent,
  CustomerSatisfactionAgent,
  QualityReviewAgent,
} from '@hemia-ai/support-agents';

Schemas de salida estructurada:

import {
  faqOutputSchema,
  supportTriageOutputSchema,
  troubleshootingOutputSchema,
  ticketOutputSchema,
  escalationOutputSchema,
  customerSatisfactionOutputSchema,
  qualityReviewOutputSchema,
} from '@hemia-ai/support-agents';

Registrar Handlers de Tools

import { InMemoryToolHandlerRegistry } from '@hemia-ai/agents-tools';
import { SUPPORT_TOOL_NAMES } from '@hemia-ai/support-agents';

const toolHandlers = new InMemoryToolHandlerRegistry();

toolHandlers.register({
  name: SUPPORT_TOOL_NAMES.createTicket,
  async execute(input, context) {
    return supportService.createTicket({
      tenantId: context.tenantId,
      title: input.title,
      description: input.description,
      priority: input.priority,
    });
  },
});

Idioma

Todas las definiciones de agentes incluyen una instrucción de idioma. Si context.locale está definido, los agentes deben responder en ese locale. Si es es-MX o empieza con es, deben responder en español.

Handlers vs LLM

Los agentes pueden correr de dos formas:

• Con handler registrado: el código del producto controla el comportamiento.
• Sin handler registrado: el runtime puede usar instructions, tools y outputSchema para ejecutar un agente respaldado por modelo.

Cuando se registra un handler custom para la misma key, outputSchema se mantiene como contrato compartido para compatibilidad entre productos.

Composición con Productos

Este pack es genérico. Los paquetes de producto deben envolverlo o componerlo cuando el comportamiento dependa de permisos, SLAs, estado de ciclo de vida, colas o sistemas externos.

Ejemplos:

• Hemia Loop puede componer support.triage y support.ticket.
• Hemia Directory puede combinar support.faq con FAQs específicas de negocio.