@hemia-ai/loop-agents

Agentes específicos para Hemia Loop.

Loop está orientado a conversación multicanal, leads, soporte, atención humana y seguimiento. Este paquete define contratos de agentes, tools, schemas y helpers de registro para aplicar reglas propias de Loop sobre los agent packs compartidos.

Relación con Agent Packs

Loop puede componer agentes de:

• @hemia-ai/conversation-agents
• @hemia-ai/support-agents
• @hemia-ai/cortex-agents
• @hemia-ai/automation-agents
• @hemia-ai/business-agents para captura y actualización de leads

Instalación

pnpm add @hemia-ai/loop-agents

Agentes

Los agentes delegan en otros agentes como sub-runs reales mediante el tool core.run_subagent (ver Delegación entre agentes). La columna "Delega en" lista los usesAgents permitidos como targetAgentKey.

| Agent key | Export | Delega en (vía core.run_subagent) | |---|---|---| | loop.router | LoopRouterAgent | ConversationRouterAgent, IntentClassifierAgent | | loop.support | LoopSupportAgent | FaqAgent, TroubleshootingAgent, KnowledgeRetrievalAgent | | loop.sales | LoopSalesAgent | LeadCaptureAgent, RagAnswerAgent | | loop.lead_qualification | LoopLeadQualificationAgent | LeadCaptureAgent, SentimentAnalysisAgent | | loop.handoff | LoopHandoffAgent | HumanHandoffAgent, ConversationSummaryAgent | | loop.summary | LoopSummaryAgent | ConversationSummaryAgent | | loop.follow_up | LoopFollowUpAgent | FollowUpAgent, FollowUpSchedulerAgent | | loop.sentiment | LoopSentimentAgent | SentimentAnalysisAgent | | loop.ticket | LoopTicketAgent | TicketAgent, SupportTriageAgent |

Delegación entre agentes

La delegación es real, no documental. El runtime expone el tool core.run_subagent (@hemia-ai/agents-runtime): cuando un agente lo invoca con un targetAgentKey, se ejecuta un sub-run completo de ese agente a través del mismo AgentRunner (con sus policies, guardrails y salida estructurada). El handler necesita la instancia del runtime, así que se registra en la wiring de la app:

import { createRunSubagentToolHandler } from '@hemia-ai/agents-runtime';

toolHandlerRegistry.register(createRunSubagentToolHandler(runtime, { maxDepth: 3 }));

Salvaguardas: el targetAgentKey debe estar en el metadata.usesAgents del agente llamante (allowlist), y la profundidad de anidación está acotada por maxDepth para evitar bucles router → router.

Reglas propias de Loop

• Respetar el estado de la conversación.
• Respetar el canal de origen.
• Saber si la conversación está en modo IA o humano.
• No responder si el humano tomó control. Esto se aplica de forma determinista: loopHumanActivePolicy bloquea (POLICY_BLOCKED) a los agentes que responden al cliente (router, support, sales, lead_qualification) cuando mode es human_active o closed. Los agentes de back-office (summary, sentiment, handoff, ticket, follow_up) siguen corriendo para apoyar al humano. Regístrala con registerLoopPolicies(ruleRegistry).
• Crear o actualizar leads.
• Crear o actualizar tickets.
• Etiquetar conversaciones.
• Manejar prioridad.
• Preparar contexto antes del handoff.
• Guardar trazabilidad de respuestas y decisiones.

Uso

El paquete no crea tickets, leads o tags por sí solo. Define los contratos de agentes y tools. Cada producto conecta esos contratos a sus servicios reales: base de datos de conversaciones, CRM, helpdesk, inbox, colas o APIs internas.

import { HemiaAgentRuntime } from '@hemia-ai/agents-runtime';
import { InMemoryToolRegistry } from '@hemia-ai/agents-tools';
import {
  LOOP_AGENT_KEYS,
  registerLoopAgents,
  registerLoopTools,
} from '@hemia-ai/loop-agents';

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

registerLoopAgents(runtime);
registerLoopTools(toolRegistry);

const result = await runtime.runAgent({
  agentKey: LOOP_AGENT_KEYS.router,
  payload: {
    message: 'Necesito ayuda con mi cuenta y quiero hablar con alguien.',
  },
  context: {
    tenantId: 'tenant_123',
    conversationId: 'conv_456',
    channel: 'whatsapp',
    mode: 'ai_active',
    priority: 'normal',
    locale: 'es-MX',
  },
});

Si el producto tiene modelGateway, puedes omitir el handler del agente y dejar que LoopTicketAgent use sus instructions, tools y outputSchema. Aun así debes registrar handlers para cada tool que el modelo pueda llamar.

Tools

| Tool name | Propósito | |---|---| | loop.get_conversation_state | Cargar estado Loop: canal, modo, prioridad, tags, lead, ticket y dueño humano. | | loop.update_conversation_state | Actualizar modo, prioridad, agente seleccionado, lead, ticket o cierre. | | loop.create_or_update_lead | Crear o actualizar lead desde la conversación. | | loop.create_or_update_ticket | Crear o actualizar ticket desde la conversación. | | loop.tag_conversation | Etiquetar conversaciones para routing, reporting y automatización. | | loop.set_priority | Manejar prioridad de conversación. | | loop.prepare_handoff_context | Preparar contexto antes del handoff humano. | | loop.record_decision_trace | Guardar trazabilidad de respuestas, tools y decisiones. |

Intenciones del router

LoopRouterAgent y ConversationRouterAgent pueden clasificar estas intenciones para enrutar sin responder de más:

• faq
• support
• sales
• lead_qualification
• complaint
• order_follow_up
• scheduling
• human_handoff
• urgent
• ticket
• follow_up
• business_info
• product
• service
• hours
• location
• contact
• unknown