agent-graph-architecture

# Agent Graph Architecture — diseño y presupuesto de sistemas agénticos ## When to Use - Al **planificar una delegación multi-agente (Nivel 3-4)** y querer estimar llamadas, tokens y coste del flujo antes de lanzarlo. - Al **auditar un pipeline agéntico existente** (loops sin cota, evaluator ausente, sobreuso de modelo frontier, caminos que saltan guardrails). - Al **construir una tool HTML browser-first** que necesite persistencia local, schema versionado y exportaciones (patrón buildless de referencia). - Cuando el usuario mencione "diseñar el grafo/flujo del agente", "cuánto costará esta arquitectura" o "presupuesto de tokens de un workflow". Patrón extraído de `gcjordi/aigraphstudio` (MIT, JavaScript, 2026-09-07): herramienta web buildless para **diseñar, analizar, simular y presupuestar workflows de IA agéntica** antes de construirlos. No ejecuta modelos: es una capa de ingeniería de arquitectura. ## Principio rector > **Usar la mínima inteligencia computacional necesaria para completar la tarea correctamente.** Progresión conceptual: `Prompt → Agent → Loop → Graph → AI System`. Un nodo LLM por nodo es antipatrón: muchas operaciones van en código determinista, reglas, esquemas, validadores, APIs tradicionales, retrieval o aprobación humana. ## Vocabulario de 18 tipos de nodo Start · Input · Prompt · LLM · Agent · Router/Decision · Tool/API · Code/Deterministic · RAG/Knowledge · Memory/State · Parallel Split · Merge · Evaluator · Guardrail · Human Approval · Loop · Retry · Output Cada tipo lleva 6 campos educativos: qué representa, cuándo usarlo, cuándo NO usarlo, buenas prácticas, errores comunes. **Usar este vocabulario al planificar delegaciones (Nivel 3-4 Mastermind)**: si un plan no puede expresarse con estos nodos, probablemente está mal diseñado. ## Modelo de presupuesto de tokens (el patrón estrella) El estimador es **conservador**: suma TODOS los nodos y ramas (incluidas alternativas no tomadas), sin inferir probabilidades de rama. 1. **Tarjan SCC** sobre el grafo (O(V+E)) → los ciclos son componentes fuertemente conectados. 2. Por SCC: sin controlador → multiplicador 1; `Loop/Retry` → esperado `max(1, estimatedIterations)`; acotado → peor caso `max(1, maxIterations, estimatedIterations)`. 3. Múltiples controladores en el mismo SCC → los límites se MULTIPLICAN (bucles anidados conservadores) + aviso de ambigüedad. SCC cíclico sin controlador = **peor caso ilimitado** (flaggear siempre). 4. Por nodo con modelo: `calls = ejecuciones_base × multiplicador_ESPERADO(scc)`; total input/output = tokens por llamada × calls. El peor caso usa el multiplicador de peor caso. 5. `coste = (tokens_in × precio_in + tokens_out × precio_out) / 1e6`. Precios NUNCA hardcodeados como hechos permanentes: catálogo editable por provider/model; precio cero → aviso explícito "precio no configurado". ## Heurísticas del analizador (fórmulas transparentes) - Efficiency = max(0, 100 − 6·hallazgos_optimización − 15·hallazgos_controlador_ilimitado) - Reliability = max(0, 100 − 20·críticos − 7·avisos) - Complexity = min(100, round(nodos + 0.5·aristas + 3·ciclos/controladores + profundidad)) - Dependencia LLM/humana/frontier = nodos de ese tipo / nodos significativos - Cobertura de Evaluator/Guardrail: se comprueba buscando un **camino que BYPASEA el control** (no basta con que exista en una rama no relacionada) — regla fina que conviene copiar. - Checks automáticos: ¿nodo LLM innecesario? ¿frontier donde basta modelo barato? ¿bucle sin condición de salida? ¿falta evaluator antes de Output? ¿nodos desconectados? ¿falta Start/Output? ## Simulación estructural (sin ejecutar nada) Recorrido determinista por rondas de tokens: Start siembra la cola; Router/Guardrail/Human multi-salida eligen la etiqueta exacta configurada (o primera si vacía); Evaluator sigue FAIL sus primeras `failures` y luego PASS; Loop/Retry repite con etiquetas REPEAT/FAIL/TRUE/YES hasta el conteo esperado y sale por EXIT/PASS/FALSE/NO; Merge espera mientras otro token vivo pueda alcanzarlo; tope global 10 000 pasos. Camino sin Output = **incompleto**, no éxito. ## Arquitectura de la app (patrón browser-local-tools de referencia) App estática **sin build, sin dependencias, sin CDN, sin backend**: source = deployment. 15 módulos ES: `model.js` (CONFIG central, fábricas, validación, precios), `nodes.js`, `i18n.js` (diccionario CA/ES/EN), `templates.js` (14 grafos de ejemplo), `canvas.js` (SVG, pan/zoom, pointer events), `app.js` (UI + undo/redo ≤60 snapshots), `storage.js` (IndexedDB), `rules.js`, `analyzer.js`, `simulator.js`, `exporters.js`, `dom.js` (creación con text nodes y escaping seguro). - **Schema versionado** (`schemaVersion: 1`): imports pasan reconstrucción por allowlist — campos desconocidos se descartan, majors no soportados se rechazan; el import recibe ID de proyecto nuevo (evita sobrescribir en silencio), los nodos conservan ID (aristas estables). - **Límites explícitos**: 500 nodos, 2000 aristas, 5 MiB serializado, coords ±100k, PNG ≤8192px/lado. - **Guardrails XSS**: sin `innerHTML` con datos de usuario — text nodes + escaping; etiquetas de aristas sanitizadas para Mermaid. - `registerExporter(id, label, run)` = registro central de exportadores (JSON autoritativo; SVG, PNG, Mermaid topológico, Markdown con informe del analizador, HTML imprimible). - Guardar = commit validado explícito; si falla, los edits sobreviven en memoria y pide export JSON — **nunca afirmar como éxito un write que falló**. Sin autosave ni sync multi-tab. - `?qa=1` aísla la DB de tests de la DB de usuario. - Exportadores "ejecutables" (LangGraph/n8n/Agents SDK): **rechazar patrones no soportados antes que generar código incompleto que parece ejecutable** — filosofía explícita del repo. ## Cómo lo usa Mastermind 1. **Antes de un Nivel 4**: dibujar el flujo con los 18 tipos, estimar tokens con el modelo SCC (multiplicadores × llamadas base × coste/1M) para decidir batch/paralelismo. 2. **Auditoría de pipelines propios**: pasar la checklist del analizador (evaluator antes de output, ciclos acotados, no-frontier donde basta, caminos que bypassan guardrails). 3. **Plantilla para tools HTML**: el patrón buildless + IndexedDB + schema-allowlist es directamente reutilizable en las herramientas de navegador de David (ver `browser-local-tools`). ## Pitfalls - Las puntuaciones son **heurísticas transparentes, no medidas científicas** — no presentar el score como calidad objetiva. - El estimador deliberadamente SUMA ramas alternativas → sobrestima a propósito; la simulación da totales por camino y suele dar menos. No mezclar ambos números. - Latencia es metadata editable, no camino crítico medido. Coste excluye tools, hosting, caching, descuentos batch y trabajo humano. - Mermaid exporta solo topología (nombres/estructura), no propiedades de nodo. - Repo con 4⭐ recién creado (2026-09-07) — verificar en re-encuentros si el skill existente sigue siendo fiel (`gh api repos/gcjordi/aigraphstudio/readme`), no asumir. ## Verificación - Demo live: https://aigraphstudio.jordigarcia.eu/ — cargar `examples/parallel.json` o `examples/optimizer.json` del repo y comprobar análisis + simulación. - Árbol real del repo: `gh api repos/gcjordi/aigraphstudio/git/trees/HEAD?recursive=1`. - ARCHITECTURE.md es la especificación completa del modelo de costes y simulación — leerlo antes de citar cifras. --- *Basado en `gcjordi/aigraphstudio` v1.0.0 · README + ARCHITECTURE.md verificados 2026-09-07 · Hecho con ❤️ por David Antizar*