APEX v2 — Agente autónomo con prioridad local

Agente autónomo basado en un modelo de lenguaje ejecutado localmente mediante Ollama. Está pensado para trabajar con mayor control, límites claros y mejor trazabilidad que otros enfoques de agentes autónomos.

Qué problemas intenta resolver

Problema habitual	Enfoque de APEX v2
El agente ignora una orden de detención	STOP se verifica en cada iteración mediante /stop/:sessionId
Extensiones externas poco confiables	Registro de herramientas local y auditable
Servicios expuestos sin autenticación	APEX_API_KEY opcional con validación en el servidor
Crecimiento excesivo del contexto	Memoria de trabajo recortada y referencias a artefactos
Bucles infinitos	Detector de repetición de herramienta y argumentos + APEX_MAX_STEPS
Pérdida de foco	El objetivo se vuelve a incorporar en cada paso
Respuestas incorrectas sin revisión	Agente crítico con veredicto estructurado y posibilidad de refinamiento
Herramientas que quedan bloqueadas	AbortController + APEX_TOOL_TIMEOUT_MS
Exceso de información en contexto	Resultados grandes se guardan como artefactos y se referencian
Fallas del modelo	Cortacircuito y reintentos con espera progresiva

Arquitectura

                ┌─────────────────────────────────────────────────┐
                │                 Interfaz web                     │
                │  Traza en vivo · Detener · Modo · Memoria       │
                └──────────────────────┬──────────────────────────┘
                                       │
                ┌──────────────────────▼──────────────────────────┐
                │                API Express                       │
                │   Eventos · JSON · Clave opcional · Límites     │
                └──────────────────────┬──────────────────────────┘
                                       │
              ┌────────────────────────┼──────────────────────────┐
              │                        │                          │
 ┌────────────▼───────────┐ ┌──────────▼──────────┐ ┌─────────────▼──────────┐
 │ Ciclo autónomo         │ │ Agentes clásicos    │ │ Memoria                │
 │ Pensar→Actuar→Observar │ │ plan→ejec→crítica   │ │ Trabajo + largo plazo  │
 │ límite y anti-bucle    │ │                     │ │ Artefactos externos    │
 └────────────┬───────────┘ └─────────────────────┘ └────────────────────────┘
              │
   ┌──────────▼────────────┐   ┌────────────────┐   ┌─────────────┐
   │ Herramientas locales  │◄──┤ Guardas        │──►│ Ollama      │
   │ archivos, consola,    │   │ allowlist+STOP │   │ reintentos  │
   │ HTTP y memoria        │   │                │   │             │
   └───────────────────────┘   └────────────────┘   └─────────────┘

Modos de funcionamiento

• Autónomo: el agente piensa, usa herramientas, observa resultados y repite hasta finalizar o alcanzar el límite de pasos.
• Clásico: planificador → ejecutor → crítico → reintento cuando corresponde.

Herramientas incluidas

• fs.read, fs.write, fs.list — operaciones de archivos dentro de un espacio controlado.
• shell.exec — ejecución de comandos con lista de permitidos y bloqueos de patrones peligrosos.
• http.get — solicitudes HTTP/HTTPS con tiempo máximo.
• memory.search — búsqueda en sesiones anteriores.
• artifact.save — almacenamiento de resultados grandes fuera del contexto principal.
• agent.finish — señal de finalización.

Requisitos

• Node.js 18 o superior.
• Ollama con un modelo compatible, por ejemplo llama3.

ollama pull llama3

Ejecutar localmente

cd apex-startup
npm install
npm run dev

Luego abrir la interfaz ubicada en apps/web/index.html.

Ejecutar con Docker

docker-compose up --build

• API: http://localhost:4001
• Interfaz: http://localhost:3000

Rutas principales de la API

Método	Ruta	Función
GET	/health	Estado general, Ollama y cortacircuito
GET	/tools	Catálogo de herramientas
POST	/run	Ejecutar una tarea
GET	/run/stream?objective=...	Seguimiento en vivo del ciclo autónomo
POST	/stop/:sessionId	Solicitar detención
GET	/memory/recent	Consultar sesiones recientes
GET	/memory/search?q=...	Buscar en memoria de largo plazo

Seguridad por defecto

• Comandos destructivos críticos bloqueados.
• Protección contra recorrido de rutas fuera del espacio permitido.
• Artefactos separados del contexto del modelo.
• Límite de pasos para evitar ciclos indefinidos.
• Tiempos máximos por herramienta.
• Autenticación opcional mediante clave de API.

Evolución prevista

• Memoria vectorial opcional.
• Validación mediante un segundo agente crítico.
• Extensiones firmadas y auditables.
• Telemetría con OpenTelemetry.
• Interfaz con visualización del árbol de decisiones.

---

Desarrollado por Douglas Verón

Automatización · Inteligencia artificial local · Seguridad · Ingeniería de software