@hemia-ai/cortex-agents

Pack reutilizable de Hemia para recuperación de conocimiento, RAG, validación de fuentes, grounding, ingesta de documentos y gaps de conocimiento.

Cortex no debería ser solo una superficie de chat. Su función principal es proveer conocimiento confiable para otros productos Hemia.

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

Uso dentro del workspace:

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

Inicio Rápido

import { HemiaAgentRuntime } from '@hemia-ai/agents-runtime';
import { InMemoryToolRegistry } from '@hemia-ai/agents-tools';
import {
  CORTEX_AGENT_KEYS,
  registerCortexAgents,
  registerCortexTools,
} from '@hemia-ai/cortex-agents';

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

registerCortexAgents(runtime);
registerCortexTools(toolRegistry);

const result = await runtime.runAgent({
  agentKey: CORTEX_AGENT_KEYS.ragAnswer,
  payload: {
    query: '¿Cuál es la política de cancelación?',
    knowledgeBaseId: 'kb_123',
  },
  context: {
    tenantId: 'tenant_123',
    knowledgeBaseId: 'kb_123',
    locale: 'es-MX',
  },
});

Agentes

| Agent key | Export | Propósito | |---|---|---| | cortex.knowledge_retrieval | KnowledgeRetrievalAgent | Recuperar conocimiento relevante desde Cortex. | | cortex.rag_answer | RagAnswerAgent | Generar respuestas con grounding usando contexto recuperado. | | cortex.source_validation | SourceValidationAgent | Validar si una respuesta está soportada por fuentes confiables. | | cortex.answer_grounding | AnswerGroundingAgent | Mantener respuestas dentro del conocimiento permitido. | | cortex.document_ingestion | DocumentIngestionAgent | Preparar documentos para RAG. | | cortex.knowledge_gap | KnowledgeGapAgent | Detectar y registrar preguntas sin respuesta. |

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

Tools

| Tool name | Alias | Propósito | |---|---|---| | cortex.retrieve_knowledge | retrieveKnowledgeTool | Recuperar conocimiento desde documentos, chunks, FAQs, políticas o catálogos. | | cortex.search_documents | searchDocumentsTool | Buscar documentos. | | cortex.search_chunks | searchChunksTool | Buscar chunks indexados. | | cortex.validate_sources | validateSourcesTool | Validar evidencia y soporte de fuentes. | | cortex.register_knowledge_gap | registerKnowledgeGapTool | Registrar gaps de conocimiento. |

Los handlers de tools son específicos de cada producto. Cortex o una integración de producto deben conectar estos contratos a su índice de búsqueda, vector store, document store o registro de gaps.

API

Exports principales:

import {
  CORTEX_AGENT_KEYS,
  CORTEX_TOOL_NAMES,
  cortexAgentDefinitions,
  cortexToolDefinitions,
  registerCortexAgents,
  registerCortexTools,
  KnowledgeRetrievalAgent,
  RagAnswerAgent,
  SourceValidationAgent,
  AnswerGroundingAgent,
  DocumentIngestionAgent,
  KnowledgeGapAgent,
} from '@hemia-ai/cortex-agents';

Schemas de salida estructurada:

import {
  knowledgeRetrievalOutputSchema,
  ragAnswerOutputSchema,
  sourceValidationOutputSchema,
  answerGroundingOutputSchema,
  documentIngestionOutputSchema,
  knowledgeGapOutputSchema,
} from '@hemia-ai/cortex-agents';

Registrar Handlers de Tools

import { InMemoryToolHandlerRegistry } from '@hemia-ai/agents-tools';
import { CORTEX_TOOL_NAMES } from '@hemia-ai/cortex-agents';

const toolHandlers = new InMemoryToolHandlerRegistry();

toolHandlers.register({
  name: CORTEX_TOOL_NAMES.retrieveKnowledge,
  async execute(input, context) {
    return cortexService.retrieveKnowledge({
      tenantId: context.tenantId,
      query: input.query,
      knowledgeBaseId: input.knowledgeBaseId,
    });
  },
});

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.

Grounding

RagAnswerAgent, SourceValidationAgent y AnswerGroundingAgent están diseñados para reducir respuestas sin soporte:

• Devolver fuentes junto con las respuestas cuando sea posible.
• Marcar falta de contexto en lugar de inventar.
• Identificar afirmaciones no soportadas.
• Bloquear o reescribir respuestas cuando el grounding no sea suficiente.

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

Otros packs y productos pueden usar Cortex como fuente confiable de conocimiento.

Ejemplos:

• Loop puede componer cortex.knowledge_retrieval y cortex.rag_answer para soporte interno.
• Directory puede usar cortex.source_validation para validar respuestas de negocio.
• Cualquier producto puede usar cortex.knowledge_gap para detectar FAQs o documentos faltantes.