Plano de Ejecución :: Arquitectura del Runtime Cognitivo (jg_agente)
"A lo que hoy se denomina 'orquestación agéntica reflexiva', en la ingeniería telemática lo llamábamos autómata finito con realimentación, detección de errores y contención de fallos. La física de los sistemas distribuidos no ha cambiado: lo que ha cambiado es la necesidad de gobernar la no-determinación de los LLMs mediante contratos estrictos y salvaguardas de ingeniería."
Código fuente e histórico de auditoría disponible en el repositorio oficial:
🔗 GitLab: gitlab.com/javiergalvez-ia/jg_agente
1. Visión y Principios del Runtime
El Plano de Ejecución (jg_agente) es el núcleo computacional y cognitivo del ecosistema. Opera como un microkernel completamente desacoplado de las interfaces de usuario, expuesto exclusivamente a través de una API REST privada construida sobre FastAPI y Python 3.12.
Su propósito fundamental es proporcionar un entorno de razonamiento estructurado, explicable y tolerante a fallos para agentes de inteligencia artificial, asumiendo una premisa ineludible: los Modelos de Lenguaje (LLMs) son componentes estocásticos y no fiables por definición, por lo que cualquier acción que interactúe con el mundo real debe estar gobernada por invariantes deterministas de ingeniería de software.
Principios Rectores de Diseño:
- Agnosticismo Radical del Core: El runtime no conoce ni asume ningún dominio vertical de negocio (ni finanzas, ni telefonía, ni DevOps). Toda capacidad operativa se inyecta dinámicamente como herramientas aisladas mediante el
PluginManagerdel SDK (jg_agente_sdk). - Contratos Inmutables Fuertemente Tipados: Toda entrada, salida y mutación del estado interno se valida mediante esquemas de Pydantic v2 (
AgentInput,AgentOutput,AgentState). Si un dato no satisface el contrato, la ejecución aborta antes de alcanzar el modelo. - Persistencia Dual y Recuperabilidad (Fail-Closed): Los puntos de control del grafo de razonamiento se persisten en PostgreSQL mediante
DualPostgresSaver. Ante cualquier interrupción de proceso, partición de red o crash del contenedor, el estado se recupera exactamente desde el último nodo consolidado. - Defensa en Profundidad y Aislamiento Perimetral: Ninguna llamada a tool se ejecuta sin pasar por el
SecurityGuard, que valida permisos, verifica el enjaulado en el workspace (directory jail) y aplica mitigación determinista de SSRF con DNS pinning a nivel socket TCP. - Reversibilidad y Patrón Saga: Toda herramienta con impacto mutacional declara obligatoriamente un método de compensación (
tool.rollback()). Si la secuencia de razonamiento fracasa a mitad de camino, el runtime ejecuta un desenrollado LIFO para restaurar el estado previo del sistema.
2. Topología del Grafo Cognitivo: La Máquina de Estados de 10 Nodos
En lugar de delegar el flujo de razonamiento en bucles de texto ciegos (while ReAct), jg_agente compila un autómata finito formal utilizando LangGraph StateGraph. El ciclo cognitivo consta de 10 nodos canónicos estructurados con bifurcaciones condicionales y guardarraíles de seguridad:
[ Entrada: AgentInput + HMAC Auth ]
│
▼
┌──────────────────┐
│ classify_input │
└─────────┬────────┘
│
¿Es saludo/conversacional?
├── SÍ ────────────────────────────────────────┐
│ │
└── NO (Requiere acción) │
│ │
▼ │
┌───────────┐ │
│ plan │ │
└─────┬─────┘ │
│ │
▼ │
┌───────────────────┐ │
│ evaluate_safety │ │
└─────────┬─────────┘ │
│ │
¿Paso HIGH/CRITICAL no aprobado? │
├── SÍ ──► ┌──────────────────┐ │
│ │ human_approval │ (Pausa HITL) │
│ └─────────┬────────┘ │
│ │ │
│ (Aprobado) │
│ ▼ │
└── NO ──► ┌──────────────────┐ │
│ execute │ │
└─────────┬────────┘ │
│ │
▼ │
┌──────────────────┐ │
│ observe │ │
└─────────┬────────┘ │
│ │
▼ │
┌──────────────────┐ │
│ verify │ │
└─────────┬────────┘ │
│ │
¿Objetivo verificado OK? │
├── SÍ ───────┼──────────────────────────┤
│ │ │
│ ▼ │
│ ┌───────────┐ │
│ │ conclude │ ◄──────────────────┘
│ └─────┬─────┘
│ │
│ ▼
│ [ Salida: AgentOutput ]
│
└── NO
├── Reintento (iteración < 3) ──► Retorna a plan
├── Error Irrecuperable ────────► ┌────────────┐
│ │ rollback │
│ └─────┬──────┘
└── Degradación / Falla ────────► ┌─────▼──────┐
│ fallback │
└────────────┘
Catálogo Funcional de Nodos:
| Nodo | Función Técnica Principal | Mecanismo de Salvaguarda |
|---|---|---|
classify_input |
Clasificador léxico y semántico inicial de la intención del usuario. | Discrimina diálogos puros de intenciones operacionales, evitando invocar modelos costosos ante saludos. |
plan |
Descompone el objetivo en pasos lógicos secuenciales mediante LLM. | Si el plan supera 3 iteraciones sin resolver, se aborta para prevenir bucles infinitos. |
evaluate_safety |
Inspecciona los pasos planificados contra la matriz de riesgo del SecurityGuard. |
Si un paso requiere nivel HIGH o CRITICAL, lo enruta obligatoriamente a supervisión humana. |
human_approval |
Emite interrupt() de LangGraph y persiste el hilo en PostgreSQL. |
Congela la ejecución y devuelve WAITING_APPROVAL hasta que el Control Plane autorice con Command(resume=...). |
execute |
Ejecuta la herramienta requerida en un hilo desacoplado con timeouts estrictos. | Enjaulado de rutas (workspace jail) y validación anti-SSRF determinista en socket TCP. |
observe |
Captura y normaliza el resultado técnico de la herramienta en el estado. | Trunca salidas volumétricas excesivas para no asfixiar la ventana de contexto del LLM. |
verify |
Evalúa si el resultado obtenido satisface los criterios de aceptación del plan. | Validación determinista contra contratos esperados; no confía en la "auto-estimación" del modelo. |
conclude |
Sintetiza la respuesta final estructurada en el contrato canónico AgentOutput. |
Asegura que la respuesta contenga trazas completas, métricas de consumo y código de estado. |
rollback |
Orquesta la compensación LIFO de las herramientas mutacionales ejecutadas. | Ejecuta tool.rollback(context) en orden inverso para garantizar consistencia transaccional. |
fallback |
Manejo de contingencias degradadas cuando la recuperación es inviable. | Retorna un informe de error estructurado con diagnóstico forense y registro en base de datos. |
3. Abstracción Multimodelo e Inferencia Soberana
El runtime desacopla el motor cognitivo de cualquier proveedor de inferencia propietario mediante una factoría unificada (app/core/llm.py):
┌─────────────────────────────────────────────────────────────────────────────┐
│ CAPA DE ABSTRACCIÓN COGNITIVA (LLM) │
└───────┬──────────────────────┬──────────────────────┬───────────────┬───────┘
│ │ │ │
▼ ▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────┐
│ Groq API │ │ OpenAI │ │ Google AI │ │ Mock │
│ (Llama-3.3- │ │ (GPT-4o, │ │ (Gemini 2.5 │ │ (Heurístico│
│ 70b ultra- │ │ modelos │ │ Flash / Pro │ │ CI/CD y │
│ baja latencia│ │ compatibles) │ │ multimodal) │ │ pruebas) │
└───────────────┘ └───────────────┘ └───────────────┘ └───────────┘
- Groq Cloud (
llama-3.3-70b-versatile): Utilizado para inferencia en tiempo real en streaming a más de 250 tokens por segundo, idóneo para ciclos reflexivos rápidos. - OpenAI y Endpoints Compatibles (vLLM, Ollama, Together): Compatibilidad con la especificación estándar de chat completions, permitiendo inferencia local soberana air-gapped.
- Google AI (Gemini 1.5 Pro / Flash): Ventana de contexto extendida para ingesta de documentos voluminosos y análisis multimodales.
- Modelo Heurístico (
MockChatModel): Motor determinista sin coste ni dependencias de red, fundamental para pipelines de integración continua (CI/CD) y desarrollo local offline.
Backoff Adaptativo ante Saturación de Inferencia (HTTP 429)
Cuando los proveedores de API saturan sus cuotas de inferencia, OpenAICompatibleChatModel no colapsa ni reintenta ciegamente:
- Inspección de Cabeceras Reales: Lee y computa dinámicamente los valores de
Retry-Afteryx-ratelimit-reset-tokens(soportando milisegundos y segundos). - Jitter Aleatorio y Suspensión Asíncrona: Si el cálculo excede la ventana inmediata, aplica
await asyncio.sleep(tiempo + jitter), liberando el bucle de eventos de FastAPI para atender otras solicitudes concurrentes.
4. Gobernanza de Seguridad en Profundidad (SecurityGuard)
La invocación de cualquier herramienta está blindada por un subsistema determinista de seguridad que actúa como un cortafuegos previo a la ejecución:
4.1 Invarianza de Seguridad (AGENTE-SEC-06)
Una regla inquebrantable del runtime establece que los permisos de usuario (incluso roles de superadministrador) solo amplían los accesos a herramientas de negocio, pero jamás pueden desactivar las salvaguardas perimetrales. Los guardarraíles son invariantes de sistema.
4.2 Mitigación Determinista de SSRF y DNS Pinning
Cuando un plugin realiza peticiones HTTP a recursos externos dictados por el LLM:
- Resuelve la dirección IP del host mediante DNS antes de abrir el socket.
- Comprueba que la IP de destino no pertenezca a rangos privados, de loopback ni de metadatos de cloud (RFC 1918:
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.0/8,169.254.169.254). - Realiza socket pinning conectando directamente a la IP validada, impidiendo de forma matemática ataques de DNS Rebinding donde el nombre de dominio cambia de IP entre la validación y la conexión.
4.3 Enjaulado de Directorio (Workspace Jail)
Cualquier herramienta que manipule archivos locales tiene su ámbito restringido de forma determinista mediante os.path.realpath(). Si una ruta resuelta no desciende estrictamente del directorio base configurado (WORKSPACE_ROOT), la ejecución es bloqueada inmediatamente con AccessDeniedError, neutralizando ataques de path traversal (../../etc/passwd).
5. Verificación Fail-Fast en Boot (validate_boot_capabilities)
Para evitar arranques silenciosos en falso donde un agente parece estar operativo pero falla en el primer requerimiento de producción por ausencia de dependencias, el servicio ejecuta una auditoría de arranque estricta:
# app/core/boot.py
def validate_boot_capabilities() -> None:
"""Verifica que el entorno satisfaga los requisitos declarados antes de abrir el puerto."""
missing_plugins = [p for p in REQUIRED_PLUGINS if not registry.has_plugin(p)]
missing_tools = [t for t in REQUIRED_TOOLS if not registry.has_tool(t)]
if missing_plugins or missing_tools:
raise BootIntegrityError(
f"Fallo de arranque: faltan plugins {missing_plugins} o tools {missing_tools}"
)
Si faltan plugins obligatorios, si el secreto HMAC no cumple la longitud mínima de seguridad (32 bytes), o si la conexión a PostgreSQL no supera la prueba de latencia, el contenedor termina con código de salida no cero, impidiendo que el orquestador (Docker/Kubernetes) lo marque como saludable (healthy).
6. Referencia de Repositorio y Especificación
El código completo del Plano de Ejecución, junto con su suite de pruebas unitarias (pytest), linters (ruff) y tipado estricto (mypy), está disponible para auditoría y evaluación técnica en el monorepo oficial:
- Repositorio GitLab: https://gitlab.com/javiergalvez-ia/jg_agente
- Licencia: MIT / Open Core Architecture
- Ecosistema: javiergalvez-ia
| Título | Plano de Ejecución :: Arquitectura del Runtime Cognitivo jg_agente |
|---|---|
| Archivo | docs/02_jg_agent/execution_plane.md |
| Descripción | Arquitectura interna, ciclo reflexivo de 10 nodos en LangGraph, contratos estrictos Pydantic v2, factoría multimodelo, mitigaciones anti-SSRF y salvaguardas de ejecución en jg_agente. |
| Autor | Javier Gálvez |
| Fecha | 2026-10-17 |
| Etiquetas |
#Execution Plane
#jg_agente
#Python 3.12
#FastAPI
#LangGraph
#StateGraph
#DualPostgresSaver
#SecurityGuard
#Zero-Trust
#Multi-Provider LLM
|