# Ingeniería de grafos en AgentSquad

**Qué es este documento.** La tesis técnica de "graph engineering" contrastada contra cómo funciona AgentSquad de verdad hoy, con los datos de dos procesos reales. Sirve para tres audiencias distintas y separa siempre lo medido de lo estimado.

**Corte:** 8 de septiembre de 2026. Código verificado en el commit `87c9a745`. Datos leídos de las tablas `graph_nodes`, `work_items` y `runs` del substrato.

**Versiones interactivas**

| Página | Para quién |
|---|---|
| [Resumen](https://playgrounds.digitalhubassist.ai/agentsquad-graph.html) | Punto de entrada, dos minutos de lectura |
| [Sin tecnicismos](https://playgrounds.digitalhubassist.ai/agentsquad-para-gerentes.html) | Gerente o director de empresa |
| [El caso de inversión](https://playgrounds.digitalhubassist.ai/pitch-agentsquad.html) | Inversionista |
| [El grafo real](https://playgrounds.digitalhubassist.ai/grafo-agentsquad.html) | Equipo técnico |

---

## 1. La tesis, y por qué importa ahora

La ingeniería de grafos no es una idea nueva. Lo nuevo es que el nodo, la pieza individual, ya es confiable. Por eso el cuello de botella se movió del nodo a las conexiones entre nodos.

Traducido al lenguaje de la administración: **ya no se trata de qué tan bueno es un asistente de inteligencia artificial, sino de cómo se divide el trabajo para que muchos asistentes buenos lo resuelvan.** Eso convierte el problema en uno de organización, no de programación.

La consecuencia práctica es que el debate cambió de terreno. Hace dos años la pregunta era si la herramienta servía. Hoy las preguntas son otras tres, y las tres son de gestión:

1. Cómo está repartido el trabajo entre las piezas.
2. Quién autoriza el resultado.
3. Si se puede reconstruir después qué pasó y por qué.

**Origen:** análisis del video *Graph Engineering explained in 8min*, de Caleb Writes Code, publicado el 29 de julio de 2026, con 80.143 vistas al momento del análisis. Documento completo: `caleb-writes-code-graph-engineering-analisis.md`.

---

## 2. Qué es un nodo, sin tecnicismos

Un **nodo** es un puesto de trabajo en una línea de producción. Tiene una sola responsabilidad, recibe algo, produce algo y se lo entrega al siguiente.

- En una fábrica sería una **estación de trabajo**.
- En una oficina sería un **cargo con funciones definidas**.
- En un procedimiento sería un **paso del proceso**.

Son la misma idea. El nodo es la unidad mínima de trabajo con un responsable claro.

Si un nodo es un puesto, el **grafo** es la ruta de producción completa: qué puestos existen, en qué orden trabajan y quién le entrega a quién.

### La diferencia que distingue a AgentSquad

Casi todas las herramientas del mercado ponen en cada puesto a un asistente genérico al que le explican por escrito qué debe hacer. AgentSquad pone en cada puesto una **función del catálogo**: está definida, tiene versión, declara qué entrega y hay un control que verifica si cumplió.

Es la diferencia entre un empleado temporal con instrucciones verbales y un puesto con manual de funciones y control de calidad.

---

## 3. Traductor de vocabulario

| Le van a decir | Significa |
|---|---|
| Nodo | Un puesto de trabajo con una sola responsabilidad |
| Grafo | La ruta de producción completa |
| Dependencia | Quién tiene que terminar antes de que otro empiece |
| Paralelismo | Cuántos puestos pueden trabajar a la vez sin estorbarse |
| Gate | El punto donde una persona firma antes de que el trabajo salga |
| Catálogo de capacidades | El manual de cargos, con versión y entregable definido |
| Evaluador | Control de calidad. Si rechaza, la línea se detiene ahí |
| Auditable | Que se puede reconstruir qué se hizo, en qué orden y por qué |
| Reintento | Volver a intentar un paso fallido, solo cuando tiene sentido |
| Ingeniería de grafos | Diseñar cómo se reparte el trabajo entre muchos |

---

## 4. Cómo funciona realmente hoy en AgentSquad

### 4.1 Sí existe un grafo, y es estricto

No es una metáfora. Hay tablas, compilador y orden topológico.

| Pieza | Ubicación | Función |
|---|---|---|
| `graph_nodes` | Postgres | Guarda `node_id`, `capability`, `depends_on`, `topo_order`, `es_gate` |
| Compilador | `orquestacion/compilador.ts` | Convierte una plantilla curada en el grafo ejecutable |
| Despachador | `orquestacion/despachador.ts` | Reclama trabajo con contratos de arrendamiento |
| Worker | `orquestacion/worker.ts` | Ejecuta la tanda |

`depends_on` son las aristas. `topo_order` es el nivel, y el código lo dice textual: *"Mismo número = independientes = despachables juntos"*.

El compilador ejecuta el algoritmo de Kahn. **Si queda un ciclo, falla cerrado y denuncia los nodos.** Una arista hacia atrás, según el propio código, *"no es ruido a ignorar sino un ciclo a denunciar"*.

Además el compilador es **puro**: no toca base de datos, ni reloj, ni azar. De ahí salen dos propiedades que la tesis general ni menciona:

- El `content_hash` sirve como clave de idempotencia.
- El grafo de una corrida vieja se puede **reconstruir** para revisar el pasado.

### 4.2 El nodo no es un agente

Esta es la diferencia central. En la tesis general, cada nodo es un agente completo con su ventana de contexto y su prompt. En AgentSquad:

```
capability: paso.operation_ref
```

**El nodo es una Operation del catálogo versionado.** Hay 51 capacidades distintas usadas en 17 grafos compilados.

Consecuencias, todas a favor:

- **El multiplicador de costo de la tesis general no aplica igual.** Ese número sale de multiplicar agentes con contexto propio. Acá se multiplican operaciones, y varias ni consultan al modelo.
- **Los nodos son auditables por contrato.** Cada uno declara esquema de salida, evaluador y recurso.
- **El catálogo es la unidad de capacidad, no la persona.** Un agente es identidad y presentación; la capacidad vive en el catálogo.

### 4.3 Los cinco patrones clásicos

| Patrón | Estado | Evidencia |
|---|---|---|
| Encadenamiento | Sí | `depends_on` más `topo_order`, 11 niveles |
| Paralelización | Sí | `Promise.allSettled` sobre los arrendamientos, hasta 5 por tanda |
| Orquestador y trabajadores | Sí | Compilador, despachador y worker separados |
| Evaluador y optimizador | Parcial | Existe `evaluator.run` y falla cerrado, pero no reescribe con la crítica |
| Enrutamiento | Sí, en otro lugar | No rutea dentro del grafo: rutea el fallo, en `router.ts` |

El router devuelve una decisión con motivo explícito y auditable: `transitorio_con_intentos`, `fallo_deterministico`, `intentos_agotados`, `decision_humana`, `evaluacion_bloqueante`, `motivo_no_reintentable`, `nodo_desconocido`.

Uno de esos motivos merece leerse. `gate_rechazado` **no se reintenta**, y la razón está escrita en el código: *"el dueño miró el trabajo y dijo que no. Reintentarlo sería volver a hacer lo mismo esperando que esta vez le guste"*. Eso no es ingeniería de grafos, es diseño de producto dentro del grafo.

### 4.4 Las guardas que la tesis general no menciona

- **Arrendamientos con token de generación**, para que un trabajador lento no pise a otro.
- **Tope de recuperaciones**: al agotarse, el ítem se marca muerto, no reintenta sin fin.
- **Orden global de bloqueos** `runs → artifact_approval_flows → work_items`, para evitar bloqueos mutuos.
- **Dos candados independientes** para que el worker no gaste dinero sin permiso: `runs.engine = 'v2'` en la consulta (dato, no configurable) y `WORKER_ORQUESTACION` (entorno). Si uno falla, el otro sigue.
- **Presupuesto reservado por corrida**, con idempotencia ante reintentos de la cola durable.

### 4.5 El motor viejo ya no existe en producción

El commit `2efb1677` retiró el motor v1 del runtime. El selector es fail closed: devuelve `v2` o `null` con motivo. El motor viejo quedó solo como canario que avisa si alguien lo despierta.

**Hoy el grafo no es una de dos rutas posibles. Es la única.**

---

## 5. El caso real, con números medidos

Proceso `bb6f4172`, ejecutado el 8 de septiembre de 2026 entre las 19:02 y las 19:12.

| Dato | Valor |
|---|---|
| Pasos ejecutados | 23, ninguno falló |
| Niveles de dependencia | 11 |
| Duración total | 10 minutos 35 segundos |
| Costo total | USD 0,7662 |
| Tokens de entrada / salida | 13.966 / 38.595 |
| Máximo trabajando a la vez | 5 |
| Aprobaciones humanas | 1, antes de publicar |

### Qué produjo en esos diez minutos

Revisó **nueve transcripciones completas de video** (131.831 caracteres), leyó los **comentarios de cinco videos** (22.539 caracteres), analizó **siete conversaciones de foro**, midió la **demanda del mercado en seis idiomas**, comparó **diez canales de la competencia** y con todo eso redactó un informe con **tres oportunidades priorizadas**, cada una atada a la evidencia que la sostiene.

El informe no se publicó solo. Quedó detenido esperando aprobación humana. **El sistema puede hacer el trabajo, pero no puede autorizarlo.**

### La forma real del grafo

| Nivel | Nodos | Ventana de cierre |
|---|---|---|
| 0 | 5 | 18 segundos |
| 1 | 4 | 13 segundos |
| 2 | 5 | 50 segundos |
| 3 | 2 | 60 segundos |
| 4 | 2 | 37 segundos |
| 5 y 6 | 1 y 1 | secuencial |

Cinco nodos cerrando en 18 segundos es paralelismo real. La forma es **ancha al principio y angosta al final**: recolecta evidencia en paralelo y la sintetiza en un embudo de un solo hilo.

---

## 6. El desglose: qué costaría a mano

La columna del medio es dato medido. Las dos de la derecha son estimaciones de cuánto tardaría una persona competente en producir lo mismo.

| Nodo | Lo que produjo (medido) | Conservador | Completo |
|---|---|---|---|
| r0 | 12 keywords a 6 idiomas y 12 juegos de consultas | 20 min | 30 min |
| r1 | 10 videos relevantes en 6 idiomas | 30 | 40 |
| r1b | métricas de 10 canales | 15 | 20 |
| r2 | comentarios de 5 videos, 22.539 caracteres | 20 | 45 |
| r3 | 7 hilos de foro | 20 | 30 |
| r5 | demanda en 6 mercados, 5 huecos | 20 | 25 |
| r6 | posiciones de búsqueda en 6 idiomas | 10 | 15 |
| r7 | métricas de 10 videos de competidores | 15 | 20 |
| **r8** | **9 transcripciones, 131.831 caracteres** | **50** | **150** |
| r9 | publicaciones recientes del canal | 10 | 10 |
| r14 | 6 barreras, 5 dolores, 5 huecos, 8 motivaciones | 30 | 60 |
| r4 | síntesis cruzada con 8 autochequeos | 45 | 90 |
| r10 | 12 keywords de oportunidad, 3 oportunidades | 20 | 30 |
| r11 | demanda de esas keywords | 10 | 15 |
| r12 | ranking de las 3 oportunidades | 15 | 20 |
| r13 | evidencia de foro atada a cada oportunidad | 20 | 30 |
| s0 a s3 | contexto del espacio de trabajo | 10 | 15 |
| s4 | redacción del informe | 40 | 60 |
| s5 | revisión contra criterios | 10 | 15 |
| s6 | publicación | 10 | 10 |
| **Total** | | **7,0 horas** | **12,2 horas** |

El nodo que domina es `r8`: unas 24.000 palabras de transcripciones. Solo leerlas a ritmo normal son dos horas.

**Multiplicadores:** 7 horas contra 10 minutos 35 son **40x** en el escenario conservador y **69x** en el completo. Con un costo real de 77 centavos, el retorno por dólar gastado supera 200x a una tarifa de 25 dólares por hora.

---

## 7. Los tres niveles de evidencia

Esta distinción es la que sostiene la credibilidad de todo lo demás.

| Nivel | Qué incluye | Origen |
|---|---|---|
| **Medido** | Tiempo, costo, volumen, tokens | Base de datos del sistema |
| **Estimado** | Horas de trabajo humano equivalente | Cálculo sobre el volumen real |
| **Supuesto** | Tarifa por hora y frecuencia de uso | Depende de cada empresa |

**Nadie cronometró a una persona haciendo este trabajo.** Esa es la única parte del cálculo que no se puede probar, y conviene decirlo antes de que lo pregunten.

---

## 8. En qué se diferencia de la tesis general

| Punto | Tesis general | AgentSquad |
|---|---|---|
| Qué es cada pieza | Un agente completo con instrucciones escritas | Una función del catálogo, con versión y contrato |
| Escala | Cientos de agentes en paralelo | 24 nodos en 11 niveles, máximo 5 a la vez |
| Consumo de modelo | Todo nodo gasta tokens | 6 de 24 nodos van a APIs externas |
| Contrato del nodo | Prompt de sistema | Esquema esperado, evaluador y recurso declarados |
| Ciclos | No se aborda | Kahn detecta el ciclo y falla cerrado |
| Autoridad final | El grafo termina y entrega | Termina en una firma humana durable |

---

## 9. El argumento de inversión, con sus límites

### Lo que se puede afirmar, y hasta dónde

| Afirmación | Evidencia | Dónde parar |
|---|---|---|
| 51 capacidades versionadas en 17 flujos | `graph_nodes`, catálogo | No están validadas por clientes |
| Una corrida completa en 10 minutos por menos de un dólar | corrida `bb6f4172` | Es una corrida, no una media |
| Grafo auditable y reconstruible | compilador puro, `content_hash` | Nunca se demostró en auditoría con un tercero |
| La IA no autoriza sola | gate humano, evaluador bloqueante | Todavía no evitó ningún incidente real |
| Una sola autoridad de ejecución | commit `2efb1677` | La migración no se validó bajo carga |
| Fallos con motivo tipado | router con 7 motivos | No hay tasa de éxito sobre volumen |
| Rigor de infraestructura | 992 archivos de prueba, 88 migraciones, 2.729 commits | Rigor no es madurez de producto |

### Lo que conviene decir primero

- **Sin ingresos.** El producto no se ha cobrado.
- **15 espacios de trabajo, todos de prueba.** Sin usuarios pagos ni retención.
- **Dos corridas, no doscientas.** Una completó los 23 pasos; la anterior falló en la síntesis.
- **Las horas humanas son estimadas.** El volumen y el costo están medidos.
- **El esfuerzo está cargado en construir.** 2.729 commits contra 15 espacios de trabajo.

### El titular

> Las herramientas de agentes de hoy generan trabajo que nadie puede auditar. AgentSquad es el sustrato donde cada decisión de la IA queda tipada, reconstruible y sujeta a autorización humana. Eso es lo que hace falta para que una empresa deje a la IA hacer trabajo que importa.

### El guion de la demo

1. **Gancho.** Tengo dos corridas de nuestro producto. Una funcionó y la otra falló. Le voy a mostrar las dos.
2. **La que funcionó.** 23 pasos, 10 minutos 35 segundos, 77 centavos.
3. **La que falló.** Nodo `s4`. Tres intentos: 23:31:48, 23:36:40 y 23:42:20. Dos por tiempo agotado del modelo, uno rechazado por el contrato editorial porque las propuestas no citaban la evidencia. El sistema decidió no reintentar y dejó la corrida marcada como parcial.
4. **Cierre.** Cualquiera le muestra la primera. Lo que compra su portafolio es poder contar la segunda con este nivel de detalle.

---

## 10. Cinco preguntas para evaluar cualquier proveedor

No hace falta saber programar para evaluar una herramienta de este tipo.

1. **Cuando esto se equivoque, ¿me van a poder decir en qué paso fue?** Si la respuesta es vaga, no hay bitácora, y sin bitácora no se puede corregir ni defender ante una auditoría.
2. **¿Quién autoriza lo que sale? ¿Puede salir algo sin que una persona lo firme?** Si el sistema publica solo, se asumió un riesgo que probablemente no se quería asumir.
3. **Si en seis meses alguien pregunta por qué se tomó esta decisión, ¿pueden reconstruirla?** Reconstruir no es tener un archivo guardado.
4. **¿Qué pasa si un paso entrega algo defectuoso? ¿El siguiente lo usa igual?** Sin control de calidad entre pasos, un error temprano contamina todo lo que sigue.
5. **¿Cuánto costó la última operación real, con el detalle?** Sin costo por operación no hay presupuesto ni comparación contra hacerlo a mano.

---

## Fuentes y advertencias

- Código verificado en el commit `87c9a745` del repositorio de AgentSquad.
- Datos de operación de las corridas `bb6f4172` (8 de septiembre, completa) y `5696d02e` (7 de septiembre, parcial).
- Tablas consultadas: `graph_nodes`, `work_items`, `runs`.
- El tiempo, el costo, los tokens y el volumen de trabajo **están medidos**.
- Las horas de trabajo humano equivalente **son estimaciones** basadas en ese volumen.
- La tarifa por hora y la frecuencia de uso **son supuestos** que cada empresa define.