@hemia-ai/automation-agents

Pack reutilizable de Hemia para tareas automáticas, recordatorios, notificaciones, workflows, asignación de tareas, seguimientos y agenda.

Este paquete provee definiciones de agentes, definiciones de tools, contratos TypeScript y JSON Schemas para automatización operativa entre productos.

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

Uso dentro del workspace:

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

Inicio Rápido

import { HemiaAgentRuntime } from '@hemia-ai/agents-runtime';
import { InMemoryToolRegistry } from '@hemia-ai/agents-tools';
import {
  AUTOMATION_AGENT_KEYS,
  registerAutomationAgents,
  registerAutomationTools,
} from '@hemia-ai/automation-agents';

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

registerAutomationAgents(runtime);
registerAutomationTools(toolRegistry);

const result = await runtime.runAgent({
  agentKey: AUTOMATION_AGENT_KEYS.followUpScheduler,
  payload: {
    conversationId: 'conv_456',
    message: 'Dar seguimiento si el usuario no responde.',
    timezone: 'America/Mexico_City',
  },
  context: {
    tenantId: 'tenant_123',
    conversationId: 'conv_456',
    locale: 'es-MX',
    timezone: 'America/Mexico_City',
  },
});

Agentes

| Agent key | Export | Propósito | |---|---|---| | automation.reminder | ReminderAgent | Crear recordatorios para citas, demos, seguimientos o tareas. | | automation.notification | NotificationAgent | Enviar notificaciones por email, WhatsApp, Slack, app o webhook. | | automation.workflow_trigger | WorkflowTriggerAgent | Disparar workflows según intención, estado o evento. | | automation.task_assignment | TaskAssignmentAgent | Asignar tareas a humanos, equipos, prioridades, SLAs o colas. | | automation.follow_up_scheduler | FollowUpSchedulerAgent | Programar seguimientos automáticos con tiempos, reintentos y mensajes. | | automation.agenda | AgendaAgent | Consultar disponibilidad, proponer horarios, agendar, reagendar o cancelar. |

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

Tools

| Tool name | Alias | Propósito | |---|---|---| | automation.schedule_follow_up | scheduleFollowUpTool | Programar seguimiento automático. | | automation.create_reminder | createReminderTool | Crear recordatorio. | | automation.send_notification | sendNotificationTool | Enviar notificación. | | automation.trigger_workflow | triggerWorkflowTool | Disparar workflow. | | automation.assign_task | assignTaskTool | Asignar tarea a humano, equipo o cola. | | automation.create_calendar_event | createCalendarEventTool | Crear, reagendar o cancelar evento de calendario. |

Los handlers de tools son específicos de cada producto. Loop, Directory, soporte interno o integraciones externas deben conectar estos contratos a su scheduler, notification service, workflow engine, task manager o calendario.

API

Exports principales:

import {
  AUTOMATION_AGENT_KEYS,
  AUTOMATION_TOOL_NAMES,
  automationAgentDefinitions,
  automationToolDefinitions,
  registerAutomationAgents,
  registerAutomationTools,
  ReminderAgent,
  NotificationAgent,
  WorkflowTriggerAgent,
  TaskAssignmentAgent,
  FollowUpSchedulerAgent,
  AgendaAgent,
} from '@hemia-ai/automation-agents';

Schemas de salida estructurada:

import {
  reminderOutputSchema,
  notificationOutputSchema,
  workflowTriggerOutputSchema,
  taskAssignmentOutputSchema,
  followUpSchedulerOutputSchema,
  agendaOutputSchema,
} from '@hemia-ai/automation-agents';

Registrar Handlers de Tools

import { InMemoryToolHandlerRegistry } from '@hemia-ai/agents-tools';
import { AUTOMATION_TOOL_NAMES } from '@hemia-ai/automation-agents';

const toolHandlers = new InMemoryToolHandlerRegistry();

toolHandlers.register({
  name: AUTOMATION_TOOL_NAMES.createReminder,
  async execute(input, context) {
    return automationService.createReminder({
      tenantId: context.tenantId,
      title: input.title,
      remindAt: input.remindAt,
      timezone: input.timezone,
    });
  },
});

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, reglas de workflow, colas, calendarios, proveedores de notificación o SLAs.

Ejemplos:

• Hemia Loop puede componer automation.follow_up_scheduler, automation.notification y automation.task_assignment.
• Hemia Directory puede componer automation.agenda y automation.reminder.