🔭 Fallas, harness y observabilidad

El nodo fan-in —el punto donde varias ramas paralelas vuelven a unirse en un solo nodo— tiene un modo de falla silencioso: una rama falla o vuelve vacía, y la unión continúa como si estuviera completa. El resultado se ve bien, está incompleto y nadie se da cuenta porque nada dio la alerta.

La forma más común de que esto ocurra: despachas una investigación a cuatro fuentes, una API falla, el nodo de esa fuente devuelve una lista vacía (no un error: vacía) y la combinación redacta el informe con tres fuentes como si fueran cuatro. Nadie recibió una excepción ni vio un log en rojo. El informe simplemente está mal.

Qué observar: la línea roja punteada de la fuente C: todavía llega a la unión, pero vacía. El nodo de merge no comprueba la cantidad, así que procesa lo que recibió y sigue. No aparece ningún error. El defecto no está en la fuente que falló, sino en la unión, que no preguntó: "¿recibí los cuatro que envié?".

Dos aristas condicionales que se apuntan entre sí son la receta más común para que un grafo se quede atascado: el revisor rechaza, el escritor reescribe, el revisor vuelve a rechazar — indefinidamente. El grafo "está funcionando" desde hace horas y el síntoma es exactamente ese: ningún error, solo consumo.

Qué observar: toda la diferencia está en la tercera arista del lado derecho, la cian, que solo existe porque alguien dibujó una salida de emergencia. Sin ella, el grafo de la izquierda solo tiene dos aristas, y ambas solo saben apuntarse entre sí.

Filtración de estado y ocurre cuando un nodo transmite más de lo debido, y el contexto limpio del siguiente nodo deja de estar limpio. El contexto limpio era justamente la ventaja que motivó armar el grafo, y este es el modo de falla que anula esa ventaja silenciosamente, sin romper nada visible.

El ejemplo clásico es el revisor. Si el revisor recibe solo el texto y el criterio de aprobación, juzga con ojos frescos. Si el revisor recibe el razonamiento del escritor junto —«lo pensé así, decidí de esta manera»—, deja de juzgar el resultado y empieza a validar el proceso. En la práctica, vuelve a aprobar el trabajo, porque ahora entiende (y simpatiza con) el motivo detrás de la elección.

Qué observar: solo cambió el contenido de la arista — no la estructura del grafo. Eso es lo que hace que las fugas de estado sean difíciles de detectar en una revisión de código: el diagrama queda idéntico, solo que el payload que circula por la arista se hizo más grande. Auditar las aristas por el schema, no solo por el diseño, es la única forma confiable de detectarlo.

State schema y es la declaración explícita de lo que lleva cada arista: nombre de los campos, formato de cada uno, qué es obligatorio y —tan importante como eso— qué explícitamente no debe pasar. Es el contrato entre dos nodos. Sin contrato, cambiar un lado rompe el otro sin aviso, y nadie sabe de quién es la culpa.

Ejecución duradera y la capacidad de un grafo para sobrevivir a una falla a mitad del camino: retomar exactamente desde donde se detuvo, no volver a ejecutar un nodo que ya terminó con éxito, y ser idempotente — ejecutar la misma entrada dos veces produce el mismo resultado, sin efectos secundarios duplicados.

Esto no es algo nuevo que haya inventado el mundo de los agentes. Es exactamente lo que la orquestación de datos resuelve desde hace décadas con ejecución duradera y caché por nodo (piensa en herramientas de pipelines de datos que reanudan un job trabado sin volver a ejecutar las etapas que ya terminaron). El grafo agéntico hereda esa solución lista: no hace falta reinventarla.

Observabilidad aquí es simple: el harness de grafo debe mostrar qué nodos se ejecutaron, en qué orden, con qué latencia y con qué costo. En un bucle, «¿por qué hizo eso?» queda enterrado en un transcript (el registro sin procesar de la conversación/ejecución) que lees línea por línea. En un grafo, el camino recorrido es un dato que consultas — si existe la instrumentación.

Sin esta instrumentación pagas todo el costo del grafo —más nodos, más aristas, más modos de falla— y no recibes la ventaja que lo justificaba: ver el sistema. Y la instrumentación no es opcional en un grafo como sí era “deseable” en un loop; sin ella, literalmente no tienes cómo responder “dónde se atascó”.

recreación ilustrativa, no es una captura de pantalla de una herramienta real.

Qué observar: la línea roja (coletar_fonte_c) es la alerta del tema 1 apareciendo en tu pantalla: sin este panel, ese timeout se convierte en el "3 de 4 fuentes" silencioso que nadie notó. La línea ámbar muestra el ciclo del tema 2 en la tercera y última vuelta permitida, con el costo acumulado visible: ves que se acerca al límite antes de que exceda el presupuesto.

Voce vai auditar o arquivo <grafo.json> deste projeto, que descreve um grafo de
agentes (nos, arestas, condicoes). Procure especificamente estes cinco defeitos
e reporte cada ocorrencia com o no/aresta exato:

1. CICLO SEM TETO DE VOLTAS
   Existe algum par de arestas condicionais que formam um ciclo (A -> B -> A)
   sem um campo tipo "max_voltas" ou equivalente? Se sim, aponte o ciclo.

2. ARESTA CONDICIONAL SEM "QUANDO"
   Toda aresta que sai de um no de decisao/roteamento declara a condicao sob a
   qual e seguida? Aponte arestas condicionais sem condicao explicita.

3. CONDICOES QUE NAO COBREM TODOS OS CASOS (ENTRADA ORFA)
   Some as condicoes de saida de cada no de decisao. Existe um caso possivel
   (ex.: nem aprovado nem reprovado) que nao tem aresta correspondente? Isso
   deixa o fluxo sem destino nesse caso.

4. JUNCAO SEM CHECAGEM DE CARDINALIDADE
   Todo no que recebe de mais de uma aresta (fan-in) tem alguma logica de
   checagem de quantidade/completude antes de seguir? Aponte juncoes que nao
   verificam se receberam todos os ramos esperados.

5. NO SEM TETO DE CUSTO
   Todo no que chama um modelo tem um limite de custo, tokens ou tempo
   declarado? Aponte nos sem nenhum limite.

Para cada defeito encontrado: cite o id do no/aresta, explique o risco em
1 frase, e sugira a correcao minima.