Agentes — Flujo y Funcionalidad

En MatrixAI, un agente es un componente pequeño y especializado que hace exactamente una cosa. No hay un agente grande que lo controle todo: hay varios agentes en cadena, cada uno con una responsabilidad concreta y con permisos acotados.

Cuando escribes un prompt como «clasifica emails como spam, normal o urgente», MatrixAI ejecuta este pipeline:

Prompt humano
    |
PromptAgent (determinista) o LLMProposalAgent (con IA externa)
    |
.semantic — un borrador estructurado del modelo
    |
PromptSupervisor — ¿se puede construir un modelo real con esto?
    |
ArchitectAgent — convierte el plan en .mxai
    |
MathematicalAgent — traduce reglas if/then a matemáticas
    |
PlannerVerifier — valida el plan completo
    |
.mxai — el modelo declarativo final
    |
Parser — convierte .mxai en IR (representación interna)
    |
VerifierAgent — valida la IR
    |
SafetyAgent — comprueba que no hay acciones reales sin sandbox
    |
PythonBackendCompiler — compila el modelo a Python ejecutable
    |
Runtime / Entrenamiento / API / Auditoría

Una analogía sencilla

Imagina que quieres construir un puente. PromptAgent es el arquitecto que interpreta el encargo del cliente. ArchitectAgent dibuja los planos. MathematicalAgent hace los cálculos estructurales. PlannerVerifier y VerifierAgent son los inspectores técnicos. SafetyAgent es la inspección de seguridad. AuditorAgent explica al cliente qué decisiones se tomaron. Ningún arquitecto puede aprobar sus propios planos.

Archivo: matrixai/agents/prompt.py

El PromptAgent convierte tu descripción en lenguaje natural en el primer artefacto estructurado: un archivo .semantic. Lo hace sin llamar a ningún LLM externo. Es completamente determinista.

Ejemplo de salida

# Prompt de entrada:
"Un sistema que clasifique emails entrantes como urgentes, normales o spam,
usando el asunto, el remitente y la puntuación de confianza"

# .semantic producido:
PROJECT EmailClassifier
INTENT classify incoming emails
MODE classification
ENTITY Email
FIELDS subject, sender, confidence_score
GOAL classify_incoming_email
ACTION send_response IF urgency > 0.85

Archivo: matrixai/agents/llm_proposal.py

Proveedores disponibles

Configuración con un LLM externo

MATRIXAI_LLM_API_KEY=tu_clave_de_api
MATRIXAI_LLM_MODEL=gpt-4o
MATRIXAI_LLM_ENDPOINT=https://api.openai.com/v1
MATRIXAI_LLM_PROVIDER_NAME=openai
MATRIXAI_LLM_CANDIDATES=3
MATRIXAI_LLM_TEMPERATURE=0.7
MATRIXAI_LLM_TIMEOUT=30
MATRIXAI_LLM_MAX_RETRIES=2
MATRIXAI_LLM_TOKEN_BUDGET=2000

# O cargados desde un archivo .env:
MATRIXAI_LLM_ENV_FILE=.env.llm

Trazabilidad de las llamadas

Cada llamada queda registrada en un LLMCallTrace con: proveedor, modelo, endpoint, hash del prompt, número de intento, latencia, HTTP status, tokens consumidos y error si lo hubo.

Archivo: matrixai/agents/prompt_supervisor.py

El PromptSupervisor es el agente más importante del sistema. Su trabajo es uno solo: decidir si una propuesta puede convertirse en un modelo real de MatrixAI. Es completamente determinista, no importa si la propuesta vino del PromptAgent o de un LLM externo.

Check 1: architect_plan         ¿Puede convertirse el .semantic en un plan?
Check 2: planner_verifier       ¿El plan cumple reglas estructurales y objetivos?
Check 3: mathematical_rules_resolved  ¿Todas las reglas if/then están traducidas?
Check 4: parser                 ¿El .mxai puede parsearse a IR canónica?
Check 5: verifier_agent         ¿La IR cumple checks de grafo, acciones y tipos?
Check 6: safety_agent           ¿Las acciones respetan el sandbox simulate_only?
Check 7: python_compiler        ¿El backend Python puede compilar el programa?

Qué devuelve si todos los checks pasan

{
  "accepted": true,
  "semantic_text": "...",
  "plan": {},
  "mxai": "PROGRAM EmailClassifier ...",
  "compiled_python": "...",
  "checks": [
    { "name": "architect_plan", "passed": true },
    { "name": "planner_verifier", "passed": true }
  ]
}

Qué devuelve si un check falla

{
  "accepted": false,
  "checks": [
    { "name": "architect_plan", "passed": true },
    { "name": "mathematical_rules_resolved", "passed": false,
      "error": "Regla 'if priority > 0.5 or urgency > 0.8' no resuelta" }
  ]
}

Archivo: matrixai/agents/architect.py

El ArchitectAgent toma el .semantic aceptado y lo convierte en un SemanticPlan estructurado y en el archivo .mxai final.

Qué lee del .semantic

Qué genera según el modo

El GoalTranslator convierte los objetivos de negocio escritos en lenguaje natural (los bloques GOAL del .semantic) en reglas concretas y verificables que el PlannerVerifier puede comprobar.

Ejemplo práctico

Si en el prompt escribes «quiero minimizar las falsas alarmas», el GoalTranslator genera una regla: «el umbral para activar cualquier acción debe ser igual o superior a 0.85». El PlannerVerifier comprueba que el modelo efectivamente tiene ese umbral. Si no lo tiene, la propuesta es rechazada antes de convertirse en .mxai. Esto es lo que significa que MatrixAI sea declarativo en un sentido fuerte: describes los objetivos, y el sistema comprueba que el modelo los cumple.

Archivo: matrixai/agents/mathematical.py

El MathematicalAgent convierte las reglas condicionales del tipo «si X entonces Y» en expresiones matemáticas continuas. Este paso es esencial porque las reglas discretas no son diferenciables (no se pueden usar en entrenamiento) y no son auditables de la misma manera.

¿Por qué convertir reglas a matemáticas?

Una regla como si riesgo > 0.8 entonces alertar tiene un salto brusco exactamente en 0.8 — de «no alertar» a «alertar». Esto crea problemas en el entrenamiento (el gradiente es cero en casi todas partes) y en la auditoría. La solución es sigmoid(20 * (riesgo - 0.8)): una función continua que se comporta de manera similar pero con una transición suave alrededor del umbral.

{
  "check": "mathematical_rules_resolved",
  "passed": false,
  "error": "Regla 'if patient.history matches pattern X' no resuelta — patrón de texto no soportado"
}

El VerifierAgent valida la IR del modelo ya parseado. Trabaja sobre el MatrixAIProgram — la representación interna después de parsear el .mxai.

El check de grafo acíclico

Un grafo con ciclos significaría dependencias circulares (A depende de B, B depende de A), lo que haría la ejecución infinita o indefinida. MatrixAI lo rechaza siempre.

Para acciones reales se requiere: archivo .mxact explícito, flag --allow-real-actions, variable MATRIXAI_ALLOW_REAL_ACTIONS=true y clave HMAC de firma.

Mensajes de seguridad

"Acción 'send_email' tiene executor_kind=real pero POLICY no es real_with_approval"
"Acción 'update_db' llama a 'database.write' fuera del espacio simulated.*"

El AuditorAgent no valida ni genera modelos. Su trabajo es convertir el resultado de una ejecución en una explicación que cualquier persona pueda entender.

Qué explica

• Si no se activó ninguna acción: por qué no, qué valores se evaluaron, qué umbral no se alcanzó
• Si una acción quedó activa: qué valor desencadenó la acción, desde qué fuente, con qué umbral
• Si una acción quedó inactiva: qué condición no se cumplió y por cuánto
• Que la ejecución fue simulada: texto explícito de que no ocurrió ningún efecto real
• Qué nodos se evaluaron: la traza completa del recorrido del dato por el grafo

Resultado de la evaluación:

El modelo clasificó este email como "urgent" con una probabilidad de 0.94.

Factores que influyeron en la clasificación:
- El score del remitente (0.95) superó el umbral de confianza (0.85)
- El asunto del email activó señales de urgencia con intensidad 0.91

Acción propuesta: send_priority_response
- Estado: SIMULADA — no se ha enviado ningún email real
- Umbral de activación: 0.85
- Valor observado: 0.94 (umbral superado)

Nodos evaluados: Email → EmailScoring → UrgencyClassifier → Categorical → Action

El OptimizerAgent analiza el modelo y sugiere mejoras. Solo sugiere: no modifica el modelo por su cuenta.

Ejemplo de informe

Informe OptimizationReport para EmailClassifier:

[SUGERENCIA] merge_linear_activation
  Nodo: UrgencyClassifier -> sigmoid_threshold
  softmax_linear + sigmoid_threshold puede fusionarse
  Impacto esperado: reducción ~15% en tiempo de inferencia

[SUGERENCIA] simplify_graph
  Nodos actuales: 9 (umbral recomendado: 7)
  Revisar si 'IntermediateScore' y 'NormalizedScore' pueden fusionarse

Sin cambios aplicados. Todas las sugerencias son informativas.

.mxai aceptado
    |
Runtime interpretado — ejecuta el modelo sin compilar, para pruebas rápidas
    |
PythonBackendCompiler — compila a Python puro para ejecución autónoma
    |
DifferentiablePythonCompiler — versión entrenable del modelo
    |
BackendContractAnalyzer — analiza la portabilidad a distintos backends
    |
Entrenamiento (P4/P5) — ajusta los parámetros con datos reales
    |
Servidor HTTP (P6) — sirve el modelo como API REST
    |
Studio (P6.5) — interfaz visual para explorar el modelo

Los 7 checks del PromptSupervisor

Variables de entorno para LLM externo

CLI

# Forma básica: ver el .mxai en pantalla
matrixai prompt "clasifica emails como spam, normal o urgente"

# Guardar el .mxai generado
matrixai prompt "clasifica emails como spam, normal o urgente" -o email.mxai

# Ver el .semantic intermedio que generó el PromptAgent
matrixai prompt "clasifica emails como spam, normal o urgente" --semantic

# Leer la descripción desde un fichero
cat mi_descripcion.txt | matrixai prompt - -o modelo.mxai

# Resultado completo como JSON (incluye .semantic, .mxai, traza y checks)
matrixai prompt "clasifica emails como spam, normal o urgente" --json

# Si el modelo generado no es lo que esperabas:
matrixai prompt "mi descripción" --semantic -o borrador.semantic
# ... editar borrador.semantic ...
matrixai supervise-prompt "mi descripción" --proposal borrador.semantic

API REST (Studio — puerto 8080)

curl -X POST http://localhost:8080/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"prompt": "clasifica emails como spam, normal o urgente"}'

# Respuesta:
# { "ok": true, "semantic_text": "...", "mxai": "PROGRAM EmailClassifier ...",
#   "pipeline_stages": [
#     { "name": "prompt_agent", "ok": true },
#     { "name": "architect",    "ok": true },
#     { "name": "verifier",     "ok": true },
#     { "name": "safety",       "ok": true },
#     { "name": "compiler",     "ok": true }
#   ],
#   "supervision_source": "deterministic" }

# Variables de entorno necesarias
export MATRIXAI_LLM_API_KEY=tu_clave_de_api
export MATRIXAI_LLM_MODEL=gpt-4o
export MATRIXAI_LLM_ENDPOINT=https://api.openai.com/v1
export MATRIXAI_LLM_PROVIDER_NAME=openai
export MATRIXAI_LLM_CANDIDATES=3
export MATRIXAI_LLM_TEMPERATURE=0.7

# Con LLM externo (requiere variables de entorno configuradas)
matrixai propose "sistema de evaluación de riesgo hipotecario" \
  --provider chat-completions-compatible --max-candidates 3

# Modo determinista (sin LLM, usa PromptAgent como stand-in)
matrixai propose "sistema de evaluación de riesgo hipotecario" \
  --provider deterministic --max-candidates 2

# Comprobar qué modo está activo en el servidor:
curl http://localhost:8080/api/studio/status
# { "ok": true, "llm_mode": { "active": true, "provider": "openai", "model": "gpt-4o" } }
# Si "active": false → el servidor usa DeterministicLLMProposalProvider (fallback)

# Supervisar un .semantic generado previamente o editado a mano
matrixai supervise-prompt "descripción original del modelo" \
  --proposal mi_modelo.semantic

# Ver todos los checks en JSON
matrixai supervise-prompt "descripción original del modelo" \
  --proposal mi_modelo.semantic --json

# Leer el resultado del PromptSupervisor programáticamente
matrixai prompt "clasifica emails" --json | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('Aceptado:', data.get('accepted', 'N/A'))
for check in data.get('checks', []):
    estado = '✓' if check['passed'] else '✗'
    print(f'  {estado} {check["name"]}')
    if not check['passed']:
        print(f'    ERROR: {check.get("error", "")}')
"

# Cuando un check falla, los siguientes aparecen con "skipped": true
# { "ok": false, "pipeline_stages": [
#     { "name": "architect_plan",              "ok": true  },
#     { "name": "mathematical_rules_resolved", "ok": false,
#       "error": "Regla 'if category matches pattern X' no resuelta" },
#     { "name": "parser",         "ok": false, "skipped": true }
#   ] }

# Convertir un .semantic existente en .mxai
matrixai architect mi_modelo.semantic -o mi_modelo.mxai

# Flujo típico: generar el .semantic primero, luego arquitectar
matrixai prompt "evalúa el riesgo de caída de pacientes" --semantic -o riesgo.semantic
matrixai architect riesgo.semantic -o riesgo_caida.mxai

# Studio: ejecutar sobre un .mxai ya existente
curl -X POST http://localhost:8080/api/studio/run-executive \
  -H "Content-Type: application/json" \
  -d '{
    "mxai": "PROGRAM RiskAssessment ...",
    "input_json": "{"age": 75, "balance_score": 0.3}",
    "mxai_name": "RiskAssessment"
  }'

# Traducir desde un fichero de reglas
matrixai mathematize reglas_negocio.txt

# Desde stdin (una regla directa)
echo "si riesgo > 0.8 entonces alertar" | matrixai mathematize -

# Múltiples reglas
cat << 'EOF' | matrixai mathematize -
si historial_impagos > 0.6 entonces rechazar
si ingresos < 15000 y deuda > 0.5 entonces revision
si score_credito > 0.7 o garantia > 100000 entonces aprobar
clasificar solicitud en aprobada, revision, rechazada
EOF

# Salida esperada (ejemplo):
# si riesgo > 0.75 entonces protocolo
#   -> sigmoid(20 * (riesgo - 0.75))   [kind: sigmoid_threshold]
#
# si edad > 80 y balance < 0.4 entonces urgente
#   -> sigmoid(20*(edad-80)) * sigmoid(20*(0.4-balance))   [kind: sigmoid_and]

# Validar un .semantic antes de arquitectar
matrixai validate-plan mi_modelo.semantic --json

# Flujo completo de validación pre-generación:
matrixai prompt "mi descripción" --semantic -o borrador.semantic
matrixai validate-plan borrador.semantic
matrixai architect borrador.semantic -o modelo.mxai
matrixai validate modelo.mxai

# Interpretar la salida:
matrixai validate-plan mi_modelo.semantic --json | python3 -c "
import json, sys
result = json.load(sys.stdin)
if result.get('ok'): print('Plan válido')
else:
    for e in result.get('errors', []):   print(f'  ERROR: {e}')
    for w in result.get('warnings', []): print(f'  WARN:  {w}')
"

# Validar el .mxai (ejecuta el VerifierAgent sobre la IR)
matrixai validate email_classifier.mxai

# Lint: errores + advertencias (más detallado que validate)
matrixai lint email_classifier.mxai

# Lint estricto para CI/CD (falla si hay cualquier advertencia)
matrixai lint email_classifier.mxai --strict

# Ver la IR que valida el VerifierAgent
matrixai parse email_classifier.mxai

# Verificar tipos (sistema de tipos P2)
matrixai typecheck email_classifier.mxai

# Ejemplo de error de validate:
# ERROR: Nodo 'EmailScoring' referenciado en GRAPH pero no declarado
# ERROR: Acción 'send_reply' usa operador 'contains' — solo: >, >=, <, <=
# WARN:  Nodo 'TempScore' declarado fuera del GRAPH (nodo aislado)

# Integración CI:
# - run: |
#     matrixai validate email_classifier.mxai
#     matrixai lint email_classifier.mxai --strict
#     matrixai typecheck email_classifier.mxai

# Ver qué permisos necesita el modelo y si respeta el sandbox
matrixai permissions email_classifier.mxai

# Salida (modelo simulado correctamente):
# Acciones declaradas:
#   - send_reply
#     Política:   simulate_only ✓
#     Llamada:    simulated.email.send ✓
#     Sandbox:    OK — no requiere permisos reales

# Salida (violación de seguridad):
# ERROR: Acción 'update_database'
#   Política:   real_execution ✗ — requiere sandbox o contrato .mxact
#   Llamada:    database.write ✗ — fuera del espacio simulated.*

# Para acciones reales (requiere contrato y habilitación explícita):
matrixai validate-actions contrato.mxact email_classifier.mxai
matrixai dry-run-action contrato.mxact email_classifier.mxai \
  --contract-name EnviarRespuesta \
  --input '{"subject": "URGENTE", "urgency_score": 0.92}'
matrixai execute-action contrato.mxact email_classifier.mxai \
  --contract-name EnviarRespuesta --allow-real-actions \
  --signing-key $MATRIXAI_ACTION_SIGNING_KEY \
  --input '{"subject": "URGENTE", "urgency_score": 0.92}'

CLI

# Ejecutar el modelo — la salida ya incluye la explicación del AuditorAgent
matrixai run email_classifier.mxai \
  --params runs/v1/params.best.json \
  --input '{"subject": "URGENTE: sistema caído", "sender_score": 0.95, "body_length": 90}'

# Clasificación: urgent (probabilidad: 0.94)
# Factores: sender_score (0.95) superó umbral 0.85
# Acción: send_priority_response — SIMULADA (no se envió ningún email real)
# Nodos: Email → EmailScoring → UrgencyClassifier → Categorical → Action

matrixai run email_classifier.mxai --params runs/v1/params.best.json \
  --input entrada.json --json | python3 -c "
import json, sys
result = json.load(sys.stdin)
print('Resultado:', result.get('result'))
for factor in result.get('influential_factors', []):
    print(f'  - {factor}')
"

API REST

# Studio — análisis ejecutivo de un modelo existente
curl -X POST http://localhost:8080/api/studio/run-executive \
  -H "Content-Type: application/json" \
  -d '{
    "mxai": "PROGRAM EmailClassifier ...",
    "input_json": "{"subject": "URGENTE: sistema caído", "sender_score": 0.95}",
    "mxai_name": "EmailClassifier"
  }'

# Studio — simular un caso guiado
curl -X POST http://localhost:8080/api/studio/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "case_id": "fall-risk",
    "input_values": { "age": 78, "balance_score": 0.28, "previous_falls": 2 }
  }'

# Producción — predicción con trazabilidad
curl -X POST http://localhost:8000/predict \
  -H "Authorization: Bearer $MATRIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"age": 78, "balance_score": 0.28, "previous_falls": 2}'

# Ver las sugerencias del OptimizerAgent
matrixai optimize email_classifier.mxai

# [SUGERENCIA] merge_linear_activation
#   Nodo: UrgencyClassifier -> sigmoid_threshold
#   softmax_linear + sigmoid_threshold puede fusionarse
#   Impacto: ~15% reducción en tiempo de inferencia

# Como JSON para procesamiento automático:
matrixai optimize email_classifier.mxai --json | python3 -c "
import json, sys
data = json.load(sys.stdin)
for s in data.get('suggestions', []):
    print(f'  [{s["kind"]}] {s["description"]}')
"

# Via API Studio (sugerencias en la respuesta de /api/analyze):
curl -X POST http://localhost:8080/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"mxai_text": "PROGRAM EmailClassifier ..."}'

Descripción en texto
        |
        |-- CLI: matrixai prompt "descripción"
        |-- CLI: matrixai propose "descripción" --provider chat-completions-compatible
        |-- API: POST /api/analyze  { "prompt": "descripción" }
        |
        v
   PromptAgent / LLMProposalAgent (genera .semantic)
        |
        |-- Inspeccionar: matrixai prompt "..." --semantic
        |-- Editar+supervisar: matrixai supervise-prompt "..." --proposal borrador.semantic
        v
   PromptSupervisor → ArchitectAgent (genera SemanticPlan + .mxai)
        |-- Directo: matrixai architect borrador.semantic -o modelo.mxai
        v
   MathematicalAgent
        |-- Directo: matrixai mathematize reglas.txt
        v
   PlannerVerifier
        |-- Directo: matrixai validate-plan borrador.semantic
        v
   Parser → VerifierAgent
        |-- Validar:  matrixai validate modelo.mxai
        |-- Detalle:  matrixai lint modelo.mxai
        |-- Tipos:    matrixai typecheck modelo.mxai
        v
   SafetyAgent
        |-- Permisos: matrixai permissions modelo.mxai
        v
   PythonBackendCompiler
        |-- Compilar:    matrixai compile modelo.mxai -o compilado.py
        |-- Portabilidad: matrixai backend-report modelo.mxai
        v
   .mxai ACEPTADO
        |
        +-- Ejecución (AuditorAgent): matrixai run modelo.mxai --input entrada.json --params params.json
        |   API producción: POST /predict
        |   API Studio:     POST /api/studio/run-executive
        |
        +-- Optimización (OptimizerAgent): matrixai optimize modelo.mxai
        |
        +-- Entrenamiento: matrixai train modelo.mxai --training contrato.mxtrain -o runs/v1/
        |
        +-- Servicio: matrixai serve modelo.mxai --params runs/v1/params.best.json --api-key CLAVE
        |
        +-- Studio:   matrixai studio --open

Script de diagnóstico completo

#!/bin/bash
# diagnostico_pipeline.sh <fichero.mxai>
MODELO=$1
echo "=== Diagnóstico del pipeline: $MODELO ==="

echo "1. Validación estructural:"
matrixai validate "$MODELO" && echo "   OK" || echo "   FALLO"

echo "2. Lint (errores + advertencias):"
matrixai lint "$MODELO" --json | python3 -c "
import json, sys
data = json.load(sys.stdin)
errors   = [d for d in data.get('diagnostics', []) if d.get('severity') == 'error']
warnings = [d for d in data.get('diagnostics', []) if d.get('severity') == 'warning']
print(f'   Errores: {len(errors)}, Advertencias: {len(warnings)}')
for e in errors: print(f'   ERROR: {e.get("message")}')
"
echo "3. Verificación de tipos:"
matrixai typecheck "$MODELO" && echo "   OK" || echo "   FALLO"

echo "4. Permisos de seguridad:"
matrixai permissions "$MODELO" --json | python3 -c "
import json, sys; data = json.load(sys.stdin)
print(f'   Estado: {data.get("safety_status", "desconocido")}')
"
echo "5. Compatibilidad de backend:"
matrixai backend-report "$MODELO" --json | python3 -c "
import json, sys; data = json.load(sys.stdin)
print(f'   differentiable_python: {data.get("compatible", "desconocido")}')
for b in data.get('blocking_issues', []): print(f'   BLOQUEANTE: {b}')
"
echo "6. Sugerencias de optimización:"
matrixai optimize "$MODELO" --json | python3 -c "
import json, sys; data = json.load(sys.stdin)
for s in data.get('suggestions', []): print(f'   -> {s.get("kind")}: {s.get("description")}')
" || echo "   Sin sugerencias"
echo "=== Diagnóstico completado ==="

# Uso:
# chmod +x diagnostico_pipeline.sh
# ./diagnostico_pipeline.sh email_classifier.mxai