🔭 Falhas, harness e observabilidade

No fan-in — o ponto onde varios ramos paralelos se juntam de volta num so no — existe um modo de falha silencioso: um ramo falha ou volta vazio, e a juncao segue em frente como se estivesse completa. O resultado sai bonito, esta incompleto, e ninguem percebe porque nada gritou.

O jeito mais comum disso acontecer: voce despacha pesquisa em quatro fontes, uma API cai, o no daquela fonte retorna lista vazia (nao erro — vazia), e o merge escreve o relatorio com tres fontes achando que sao quatro. Ninguem recebeu excecao, ninguem viu log vermelho. O relatorio so esta errado.

O que olhar: a linha vermelha tracejada da fonte C — ela ainda chega na juncao, so que vazia. O no de merge nao tem nenhuma checagem de quantidade, entao ele processa o que recebeu e segue. Nenhum erro sobe. O defeito nao esta na fonte que falhou; esta na juncao que nao perguntou "recebi os quatro que despachei?".

Duas arestas condicionais que se apontam sao a receita mais comum de um grafo travado: o revisor reprova, o escritor reescreve, o revisor reprova de novo — indefinidamente. O grafo "esta rodando" ha horas e o sintoma e exatamente esse: nenhum erro, so consumo.

O que olhar: a diferenca inteira esta na terceira aresta do lado direito, a ciano, que so existe porque alguem desenhou uma saida de emergencia. Sem ela, o grafo da esquerda so tem duas arestas — e as duas so sabem apontar uma pra outra.

Vazamento de estado e quando um no passa adiante mais do que devia, e o contexto limpo do no seguinte deixa de ser limpo. Contexto limpo era exatamente a vantagem que motivou montar o grafo — e esse e o modo de falha que anula essa vantagem, silenciosamente, sem quebrar nada visivel.

O exemplo classico e o revisor. Se o revisor recebe so o texto e o criterio de aprovacao, ele julga com olhos frescos. Se o revisor recebe o raciocinio do escritor junto — "pensei assim, decidi assado" — ele para de julgar o resultado e comeca a validar o processo. Na pratica, ele volta a carimbar o trabalho, porque agora entende (e simpatiza com) o motivo por tras da escolha.

O que olhar: so a aresta mudou de conteudo — nao a estrutura do grafo. Isso e o que torna vazamento de estado dificil de flagrar em revisao de codigo: o diagrama fica identico, so o payload que trafega dentro da aresta engordou. Auditar arestas pelo schema, nao so pelo desenho, e a unica forma confiavel de pegar isso.

State schema e a declaracao explicita do que cada aresta carrega: nome dos campos, formato de cada um, o que e obrigatorio, e — tao importante quanto — o que explicitamente nao deve passar. E o contrato entre dois nos. Sem contrato, mudar um lado quebra o outro sem aviso, e ninguem sabe de quem e a culpa.

Execucao duravel e a capacidade de um grafo sobreviver a uma falha no meio do caminho: retomar exatamente de onde parou, nao refazer um no que ja terminou com sucesso, e ser idempotente — rodar a mesma entrada duas vezes produz o mesmo resultado, sem efeito colateral duplicado.

Isso nao e novidade que o mundo de agentes inventou. E exatamente o que orquestracao de dados resolve ha decadas com execucao duravel e cache por no (pense em ferramentas de pipeline de dados que retomam um job travado sem refazer as etapas que ja completaram). Grafo agentico herda essa solucao pronta — nao precisa reinventar.

Observabilidade aqui e simples: o harness de grafo precisa mostrar quais nos rodaram, em que ordem, com que latencia e com que custo. Num loop, "por que ele fez isso?" fica enterrado num transcript (o log bruto da conversa/execucao) que voce le linha a linha. Num grafo, o caminho percorrido e um dado que voce consulta — se a instrumentacao existir.

Sem essa instrumentacao, voce paga o preco inteiro do grafo — mais nos, mais arestas, mais modos de falha — e nao recebe a vantagem que o justificava: enxergar o sistema. E instrumentacao nao e opcional em grafo do jeito que era "desejavel" em loop; sem ela voce literalmente nao tem como responder "onde travou".

recriacao ilustrativa, nao e screenshot de ferramenta real.

O que olhar: a linha vermelha (coletar_fonte_c) e o alerta do topico 1 batendo na sua tela — sem esse painel, esse timeout vira o "3 de 4 fontes" silencioso que ninguem percebeu. A linha ambar mostra o ciclo do topico 2 na terceira e ultima volta permitida, com custo acumulado visivel — voce ve o teto se aproximando antes dele estourar o orcamento.

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.