# Agent Graph Architecture

> Usa al diseñar y presupuestar grafos de IA agéntica.

- Skill: `ntizar/agent-graph-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ntizar/agent-graph-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ntizar/agent-graph-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: ntizar (https://skillmd.com/u/ntizar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ntizar/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*