@hemia-ai/conversation-agents

Pack reutilizable de Hemia para flujos conversacionales genéricos.

Este paquete provee definiciones de agentes, definiciones de tools, contratos TypeScript, policies, guardrails y JSON Schemas para enrutamiento, clasificación de intención, resúmenes, análisis de sentimiento, handoff humano, seguimiento y detección de idioma.

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.
• @hemia-ai/agents-policies para policies reutilizables de ejecución.
• @hemia-ai/agents-guardrails para guardrails reutilizables de entrada.

Instalación

pnpm add @hemia-ai/conversation-agents

Uso dentro del workspace:

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

Inicio Rápido

import { HemiaAgentRuntime } from '@hemia-ai/agents-runtime';
import { InMemoryToolRegistry } from '@hemia-ai/agents-tools';
import {
  CONVERSATION_AGENT_KEYS,
  registerConversationAgents,
  registerConversationTools,
} from '@hemia-ai/conversation-agents';

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

registerConversationAgents(runtime);
registerConversationTools(toolRegistry);

const result = await runtime.runAgent({
  agentKey: CONVERSATION_AGENT_KEYS.router,
  payload: {
    message: 'Necesito hablar con alguien, esto no se ha resuelto.',
    allowedAgentKeys: ['support.triage', 'conversation.human_handoff'],
  },
  context: {
    tenantId: 'tenant_123',
    conversationId: 'conv_456',
    channel: 'whatsapp',
    mode: 'ai_active',
    locale: 'es-MX',
  },
});

Agentes

| Agent key | Export | Propósito | |---|---|---| | conversation.router | ConversationRouterAgent | Enrutar conversación por intención, canal, prioridad, contexto y agentes permitidos. | | conversation.intent_classifier | IntentClassifierAgent | Clasificar mensaje como FAQ, soporte, ventas, queja, agenda, handoff, urgente, seguimiento o desconocido. | | conversation.summary | ConversationSummaryAgent | Resumir historial para almacenamiento, handoff, seguimiento o revisión humana. | | conversation.sentiment_analysis | SentimentAnalysisAgent | Detectar sentimiento, frustración, urgencia y señales de riesgo. | | conversation.human_handoff | HumanHandoffAgent | Decidir cuándo escalar a una persona y preparar contexto. | | conversation.follow_up | FollowUpAgent | Decidir si una conversación abierta necesita seguimiento. | | conversation.language_detector | LanguageDetectorAgent | Detectar idioma, locale, confianza y tono esperado de respuesta. |

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

Tools

| Tool name | Alias | Propósito | |---|---|---| | conversation.classify_intent | classifyIntentTool | Clasificar intención del mensaje. | | conversation.detect_language | detectLanguageTool | Detectar idioma y locale. | | conversation.get_context | getConversationContextTool | Cargar contexto de conversación. | | conversation.update_state | updateConversationStateTool | Actualizar modo, agente seleccionado, prioridad o motivo de handoff. | | conversation.summarize | summarizeConversationTool | Resumir historial de conversación. |

Los handlers de tools son específicos de cada producto. Loop, Directory, un webchat o soporte interno deben conectar estos contratos a su base de datos, CRM, inbox o servicios de canal.

API

Exports principales:

import {
  CONVERSATION_AGENT_KEYS,
  CONVERSATION_TOOL_NAMES,
  conversationAgentDefinitions,
  conversationToolDefinitions,
  registerConversationAgents,
  registerConversationTools,
  ConversationRouterAgent,
  IntentClassifierAgent,
  ConversationSummaryAgent,
  SentimentAnalysisAgent,
  HumanHandoffAgent,
  FollowUpAgent,
  LanguageDetectorAgent,
} from '@hemia-ai/conversation-agents';

Schemas de salida estructurada:

import {
  conversationRouterOutputSchema,
  intentClassifierOutputSchema,
  conversationSummaryOutputSchema,
  sentimentAnalysisOutputSchema,
  humanHandoffOutputSchema,
  followUpOutputSchema,
  languageDetectorOutputSchema,
} from '@hemia-ai/conversation-agents';

Registrar Handlers de Tools

import { InMemoryToolHandlerRegistry } from '@hemia-ai/agents-tools';
import { CONVERSATION_TOOL_NAMES } from '@hemia-ai/conversation-agents';

const toolHandlers = new InMemoryToolHandlerRegistry();

toolHandlers.register({
  name: CONVERSATION_TOOL_NAMES.getConversationContext,
  async execute(input, context) {
    return conversationService.getContext({
      tenantId: context.tenantId,
      conversationId: input.conversationId,
    });
  },
});

Contexto

Los agentes conversacionales esperan que los productos provean este contexto:

{
  tenantId: string;
  conversationId: string;
  contactId?: string;
  channel: 'webchat' | 'whatsapp' | 'instagram' | 'email' | 'messenger';
  mode: 'ai_active' | 'human_active' | 'closed';
  locale: string;
}

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.

Policies y Guardrails

El pack incluye helpers para reforzar la regla de plataforma: no responder con AI cuando la conversación está en human_active o closed.

import {
  humanActiveConversationGuardrail,
  humanActiveConversationPolicy,
} from '@hemia-ai/conversation-agents';

humanActiveConversationPolicy puede registrarse en el PolicyEngine de un producto. humanActiveConversationGuardrail puede registrarse en un GuardrailRunner como guardrail de entrada.

Ambos helpers leen mode o conversationMode desde metadata, context, input o payload. En producción, pasa el modo de conversación por contexto o metadata para que la regla sea explícita.

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 datos de producto, permisos, estado de ciclo de vida o sistemas externos.

Ejemplos:

• Hemia Loop puede componer conversation.router, conversation.human_handoff y conversation.summary.
• Hemia Directory puede componer conversation.summary para resúmenes de conversación orientados al dueño del negocio.