SENTINEL AGENT — un constructor de aplicaciones operativas agénticas

La capa de comandos de IA para una ontología operativa estilo Foundry: un agente LLM que se conecta a través de MCP, responde preguntas en lenguaje natural con datos reales consultados, propone acciones aprobadas por humanos y genera paneles operativos bajo demanda — una herramienta operativa auto-construida, al estilo Palantir AIP.

Linaje: este proyecto evoluciona el agente generador de sitios web de IA que construí para Locari (mi SaaS de generación de leads — en producción en vivo; repositorio privado) de "LLM genera un sitio web" a "LLM opera sobre una ontología empresarial con gobernanza": el mismo ADN de bucle de agente, pero cada capacidad ahora está tipada, en lista blanca, previsualizada, aprobada por humanos y auditada. Se empareja con PACIFIC SENTINEL (Proyecto 1), cuya ontología FastAPI este agente puede consumir directamente.

La demo de 3 indicaciones

Ejecuta todo (sin conexión, no se necesita clave API):

.venv/bin/python scripts/demo.py

O escribe estos en la aplicación web:

Related MCP server: Enterprise Architecture MCP Server

¿Qué es MCP y cómo refleja esto a Palantir AIP?

MCP (Model Context Protocol) es un protocolo abierto que proporciona a un LLM una superficie de herramientas tipada, descubrible y acotada sobre sistemas externos. Un servidor expone herramientas (nombre + descripción + esquema JSON); cualquier cliente — un agente, un IDE, una aplicación de chat — se conecta, las lista y las llama. El límite del protocolo es el límite de gobernanza: el modelo solo puede hacer lo que el servidor expone.

Este proyecto es una miniatura de la arquitectura AIP de Palantir:

Cómo funciona el humano en el bucle

 user ──ask──▶ Agent (LLM)                 MCP server                FastAPI (operator)
                │  propose_action(...) ──▶ validate params
                │                          run constraint checks
                │                          build before/after PREVIEW   (no mutation)
                │ ◀── proposal + action_id ─┘
 UI shows preview card ──── human clicks Approve ──▶ approve_action(operator_key)
                                                     └─ mints SINGLE-USE token
                                                   execute_action(token)
                                                     ├─ re-validates vs CURRENT state
                                                     ├─ applies the change
                                                     └─ audit log: proposed→approved→executed

Tres capas de aplicación mantienen al agente solo como proponente:

1. Lista blanca — approve_action / reject_action / execute_action se eliminan de la lista de herramientas del LLM; el bucle del agente rechaza cualquier llamada a una herramienta que no se le haya dado.

2. Restricción de capacidad — la aprobación requiere una OPERATOR_KEY que existe solo en el proceso del servidor de orquestación (inyectada en el entorno del subproceso MCP). Ningún contexto del LLM la contiene nunca, por lo que un agente no puede acuñar tokens de aprobación ni siquiera en principio.

3. Mecánica de tokens — los tokens son de un solo uso (secrets.compare_digest, quemados en el primer uso) y la ejecución vuelve a validar cada restricción contra el estado actual, por lo que una aprobación obsoleta no puede sobregirar un depósito.

La misma filosofía rige los paneles: el agente emite una especificación JSON estrictamente validada (extra="forbid", 3 tipos de widget, tamaños acotados) que componentes React fijos interpretan — nunca HTML, JSX o código ejecutable.

Arquitectura

 React 18 + Vite + TS + Tailwind          FastAPI (port 8100)              MCP server (stdio subprocess)
 ┌──────────────┬───────────────┐   WS    ┌──────────────────────┐  MCP    ┌─────────────────────────┐
 │ Chat panel   │ Actions cards │ ◀─────▶ │ /ws  agent events    │ ◀─────▶ │ 9 tools over ontology   │
 │ (markdown)   │ Live trace    │  HTTP   │ /actions/{id}/approve│  stdio  │ ┌─ StubOntology (dflt)  │
 │              │ Dashboard     │ ◀─────▶ │ /actions/{id}/reject │         │ └─ HttpOntology ──▶ Project 1
 │              │ canvas        │         │ /audit  /health      │         │    (pacific-sentinel)
 └──────────────┴───────────────┘         │ OpsAgent loop + LLM  │         └─────────────────────────┘
                                          │ (Claude ⟷ MockLLM)  │
                                          └──────────────────────┘

Ejecútalo

# Backend
python3.11 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest                  # 60 tests, fully offline
.venv/bin/python scripts/demo.py            # scripted 3-prompt demo (mock LLM)
.venv/bin/python scripts/smoke_mcp.py       # raw MCP stdio smoke run

# CLI
.venv/bin/python -m ops_agent.cli --llm mock "Which units are critically low on water?"

# Web app: API on :8100, frontend on :5174
LLM_MODE=mock .venv/bin/python -m uvicorn ops_agent.server:app --port 8100
cd frontend && npm install && npm run dev   # open http://localhost:5174
npm test                                    # 8 Vitest component tests

# Real LLM (claude-opus-4-8; key read from env, never hardcoded)
export ANTHROPIC_API_KEY=sk-ant-...
.venv/bin/python -m ops_agent.cli "Which units are critically low on water?"

# Against Project 1's live ontology instead of the stub
ONTOLOGY_BACKEND=http ONTOLOGY_API_URL=http://localhost:8000 ...

Modos LLM — LLM_MODE=auto (predeterminado: en vivo si ANTHROPIC_API_KEY está configurada, si no, simulado) / mock / live. El MockLLM se comporta como un modelo de llamada a herramientas (consulta de fundamentación → consulta filtrada → respuesta; análisis de acción; construcción de panel) para que cada flujo — incluidas las pruebas y la demo — se ejecute sin conexión y de manera determinista.

Hitos

• M1 Servidor MCP: herramientas de ontología de solo lectura sobre un backend intercambiable + pruebas

• M2 Bucle del agente: llamada a herramientas LLM sobre MCP, lista blanca, eventos de auditoría, CLI

• M3 Transmisión WebSocket FastAPI + interfaz de chat/rastreo React

• M4 Proponer → aprobar humano (clave de operador + token de un solo uso) → ejecutar → auditar

• M5 Generación de especificación de panel (JSON seguro) + renderizador React (recharts)

• M6 Script de demo, capturas de pantalla, este README