🔭 Failures, harness, and observability

A fan-in node—the point where several parallel branches come back together at a single node—has a silent failure mode: one branch fails or returns empty, and the join moves on as if it were complete. The result looks polished, but it’s incomplete, and no one notices because nothing raised an alarm.

The most common way this happens: you dispatch research across four sources, one API goes down, that source’s node returns an empty list (not an error—empty), and the merge writes the report with three sources, thinking there are four. Nobody got an exception, nobody saw a red log. The report is just wrong.

What to look at: the red dashed line from source C—it still reaches the join, just empty. The merge node doesn’t check the quantity, so it processes what it received and continues. No error is raised. The defect isn’t in the source that failed; it’s in the join that didn’t ask, "Did I receive all four that I dispatched?"

Two conditional edges pointing to each other are the most common recipe for a stuck graph: the reviewer rejects, the writer rewrites, the reviewer rejects again — indefinitely. The graph “has been running” for hours, and the symptom is exactly that: no error, just consumption.

What to look at: the entire difference is in the third edge on the right, the cyan one, which exists only because someone designed an emergency exit. Without it, the graph on the left has only two edges—and both can only point to each other.

State leakage is when a node passes along more than it should, and the next node’s clean context is no longer clean. Clean context was exactly the advantage that motivated building the graph—and this is the failure mode that silently cancels out that advantage without visibly breaking anything.

The classic example is the reviewer. If the reviewer receives only the text and the approval criteria, they judge it with fresh eyes. If the reviewer receives the reasoning the writer’s thought process too—“I thought about it this way, then decided that”—it stops judging the result and starts validating the process. In practice, it goes back to approving the work, because it now understands (and empathizes with) the reason behind the choice.

What to look at: only the edge's content changed — not the graph's structure. That's what makes state leakage hard to spot in code review: the diagram looks identical; only the payload traveling along the edge has grown. Audit edges by schema, not just by looking at the diagram; it’s the only reliable way to catch this.

State schema is the explicit declaration of what each edge carries: field names, each field’s format, what’s required, and—just as importantly—what’s explicitly no must pass. It’s the contract between two nodes. Without a contract, changing one side breaks the other without warning, and nobody knows who’s responsible.

Durable execution is a graph’s ability to survive a failure along the way: resume exactly where it left off, not redo a node that already finished successfully, and be idempotent — running the same input twice produces the same result, with no duplicated side effects.

This isn't something new invented by the agent world. It's exactly what data orchestration has solved for decades with durable execution and per-node caching (think of data pipeline tools that resume a stuck job without rerunning steps that have already completed). Agentic graphs inherit this ready-made solution — there's no need to reinvent it.

Observability here it’s simple: the graph harness needs to show which nodes ran, in what order, with what latency and cost. In a loop, “why did it do that?” gets buried in a transcript (the raw conversation/execution log) that you read line by line. In a graph, the path taken is data you can inspect — if instrumentation exists.

Without this instrumentation, you pay the full cost of the graph—more nodes, more edges, more failure modes— and don’t get the advantage that justified it: seeing the system. And instrumentation isn’t optional in a graph the way it was “desirable” in a loop; without it, you literally have no way to answer “where did it get stuck?”

illustrative recreation, not a screenshot of a real tool.

What to look at: the red line (coletar_fonte_c) is the warning from topic 1 appearing on your screen—without this panel, that timeout becomes the silent "3 of 4 sources" that no one noticed. The amber line shows the cycle from topic 2 on the third and final allowed turn, with the accumulated cost visible—you see the limit approaching before it blows the budget.

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.