@hemia-ai/business-agents

Pack reutilizable de Hemia para negocios, productos, servicios, horarios, ubicación, contacto y captura de leads.

Este paquete provee definiciones de agentes, definiciones de tools, contratos TypeScript y JSON Schemas para flujos orientados a negocios. Está diseñado para Hemia Directory, pero también puede reutilizarse en Hapso, Tours AI, landing widgets y asistentes para negocios locales.

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/business-agents

Uso dentro del workspace:

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

Inicio Rápido

import { HemiaAgentRuntime } from '@hemia-ai/agents-runtime';
import { InMemoryToolRegistry } from '@hemia-ai/agents-tools';
import {
  BUSINESS_AGENT_KEYS,
  registerBusinessAgents,
  registerBusinessTools,
} from '@hemia-ai/business-agents';

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

registerBusinessAgents(runtime);
registerBusinessTools(toolRegistry);

const result = await runtime.runAgent({
  agentKey: BUSINESS_AGENT_KEYS.hours,
  payload: {
    businessId: 'business_456',
    query: '¿Abren los domingos?',
  },
  context: {
    tenantId: 'tenant_123',
    businessId: 'business_456',
    channel: 'directory_webchat',
    visitorId: 'visitor_789',
    locale: 'es-MX',
  },
});

Agentes

| Agent key | Export | Propósito | |---|---|---| | business.profile | BusinessProfileAgent | Responder preguntas sobre el perfil público del negocio. | | business.hours | BusinessHoursAgent | Responder horarios, disponibilidad, días festivos y horarios especiales. | | business.faq | BusinessFaqAgent | Responder FAQs específicas del negocio. | | business.product_catalog | ProductCatalogAgent | Responder disponibilidad, precios, variantes y detalles de productos. | | business.service_catalog | ServiceCatalogAgent | Responder detalles, duración, costo, requisitos y disponibilidad de servicios. | | business.location | BusinessLocationAgent | Responder dirección, sucursales, cobertura y cómo llegar. | | business.contact | BusinessContactAgent | Proveer WhatsApp, teléfono, email, sitio web y redes sociales. | | business.lead_capture | LeadCaptureAgent | Convertir una conversación en contacto o prospecto. |

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

Tools

| Tool name | Alias | Propósito | |---|---|---| | business.get_profile | getBusinessProfileTool | Obtener datos públicos del perfil del negocio. | | business.get_hours | getBusinessHoursTool | Obtener horarios normales del negocio. | | business.get_special_hours | getSpecialHoursTool | Obtener cierres, días festivos y horarios excepcionales. | | business.search_faq | searchBusinessFaqTool | Buscar FAQs del negocio. | | business.search_product_catalog | searchProductCatalogTool | Buscar datos del catálogo de productos. | | business.search_service_catalog | searchServiceCatalogTool | Buscar datos del catálogo de servicios. | | business.get_location | getBusinessLocationTool | Obtener ubicación, sucursales, cobertura y direcciones. | | business.get_contact | getBusinessContactTool | Obtener canales públicos de contacto. | | business.create_lead | createBusinessLeadTool | Crear un lead o contacto interesado. |

Los handlers de tools son específicos de cada producto. Directory, Hapso, Tours AI o widgets deben conectar estos contratos a su base de datos, catálogo, CRM o lead store.

Contexto

Contexto mínimo recomendado:

{
  tenantId: 'tenant_123',
  businessId: 'business_456',
  channel: 'directory_webchat',
  visitorId: 'visitor_789',
  locale: 'es-MX',
}

tenantId viene de AgentContext; businessId, channel, visitorId y locale están modelados por BusinessAgentContext.

API

Exports principales:

import {
  BUSINESS_AGENT_KEYS,
  BUSINESS_TOOL_NAMES,
  businessAgentDefinitions,
  businessToolDefinitions,
  registerBusinessAgents,
  registerBusinessTools,
  BusinessProfileAgent,
  BusinessHoursAgent,
  BusinessFaqAgent,
  ProductCatalogAgent,
  ServiceCatalogAgent,
  BusinessLocationAgent,
  BusinessContactAgent,
  LeadCaptureAgent,
} from '@hemia-ai/business-agents';

Schemas de salida estructurada:

import {
  businessProfileOutputSchema,
  businessHoursOutputSchema,
  businessFaqOutputSchema,
  productCatalogOutputSchema,
  serviceCatalogOutputSchema,
  businessLocationOutputSchema,
  businessContactOutputSchema,
  leadCaptureOutputSchema,
} from '@hemia-ai/business-agents';

Registrar Handlers de Tools

import { InMemoryToolHandlerRegistry } from '@hemia-ai/agents-tools';
import { BUSINESS_TOOL_NAMES } from '@hemia-ai/business-agents';

const toolHandlers = new InMemoryToolHandlerRegistry();

toolHandlers.register({
  name: BUSINESS_TOOL_NAMES.getBusinessProfile,
  async execute(input, context) {
    return businessService.getProfile({
      tenantId: context.tenantId,
      businessId: input.businessId,
      locale: input.locale,
    });
  },
});

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 datos de producto, permisos, registros privados, disponibilidad en tiempo real o reglas de ciclo de vida.

Ejemplos:

• Hemia Directory puede componer business.profile, business.faq y business.lead_capture.
• Hapso o Tours AI pueden componer business.hours, business.location y business.contact.