🕸️ Graph Engineering na pratica
Agora que voce sabe o que e um grafo e onde o loop trava: como se constroi um de verdade. No, aresta e estado num sistema de agentes; a diferenca entre o organograma que fica e o trabalho que passa; e os modos de falha que so existem porque voce montou um grafo.
O que olhar: abrir em N e depois juntar (fan-out/fan-in) e o movimento que um loop simplesmente nao faz — ele so anda em fila indiana. Cada caixa ciano e um loop inteiro com contexto proprio, nao um passo dentro do mesmo loop. E a aresta vermelha de volta e o detalhe que transforma isso de um DAG bonitinho num grafo com ciclo de verdade — e e por isso que ela precisa de um teto de voltas, como qualquer ciclo da Trilha 2.
Mapa da trilha
Conteudo detalhado
🧩 Nos, arestas e estado
As tres pecas de um grafo agentico e o que muda quando o no deixa de ser uma caixa de desenho e vira uma invocacao de agente com modelo, ferramentas e permissoes proprios.
Um no pode ser um agente, uma chamada de modelo, um pedaco de codigo comum ou uma decisao humana. Nem todo no precisa de IA.
No de codigo deterministico e mais barato e mais confiavel. Usar modelo onde um `if` resolve e desperdicio.
O no e a unidade minima de trabalho do grafo. Misture nos de codigo e nos de agente conforme a necessidade real.
A aresta e onde mora o roteamento: "se aprovado siga, se reprovado volte". Aresta condicional e o que separa um grafo de uma fila.
Sem aresta condicional voce tem uma sequencia fixa, nao um grafo. E a condicao que da flexibilidade real ao sistema.
Aresta = decisao. No = trabalho. Separar essas duas responsabilidades e o que deixa o grafo legivel.
O que exatamente passa de um no pro outro. Passar a conversa inteira anula o ganho de contexto limpo; passar de menos faz o no seguinte trabalhar as cegas.
O estado e o contrato entre nos. Acertar o tamanho dele e o que faz o grafo entregar contexto limpo de verdade.
Passe o suficiente pra decidir, nunca o historico completo por reflexo. E a base do state schema do modulo 4.3.
Modelo, ferramentas, permissoes, instrucoes e ate orcamento podem ser diferentes por no. Modelo caro no passo dificil, barato no facil.
Ferramenta de escrita so no no que precisa escrever reduz risco e custo. Configuracao por no e o que paga o grafo.
Cada no e um mini-agente configuravel: modelo, tools, prompt e permissao proprios, nao um clone do vizinho.
Um grafo de um no so, com todas as ferramentas e todas as instrucoes, rodando ate acabar: isso e loop reinventado, e a estrutura nao esta fazendo nada.
Se voce nao consegue dar configuracoes diferentes a dois nos, provavelmente nao precisava de dois nos.
Grafo degenerado e o antipadrao mais comum de quem "converte" um loop pra grafo so no nome.
No grande demais e o grafo nao ajuda; pequeno demais e voce paga sobrecarga de coordenacao em cima de trabalho trivial.
Regra pratica: um no por mudanca de contexto, de ferramenta ou de responsabilidade. Isso evita os dois extremos.
Granularidade e decisao de design, nao regra fixa — mas tem um heuristico simples pra guiar a escolha.
🏢 Org graph x work graph
Dois grafos convivem no mesmo sistema — a organizacao estavel de agentes e o trabalho efemero de hoje. Confundir os dois e a causa mais comum de sistema bagunçado.
Agentes de vida longa com papeis nomeados (pesquisador, escritor, validador, publicador), donos de dominio, com memoria acumulada.
E o organograma da sua empresa, onde cada caixa e um agente rodando um loop. So muda quando voce redeploya.
Org graph = estabilidade + identidade. Papel nomeado, memoria propria, dono de dominio.
Efemero, montado pra um pedido especifico e descartado depois. Muda a cada execucao.
Confundir work graph com org graph faz voce redesenhar a organizacao inteira a cada tarefa nova — errado e caro.
Org graph = quem existe. Work graph = o que se faz agora. Sao dois grafos, nao um so.
O de seguranca cuida de autenticacao, permissoes e logs; o de dados cuida de esquema e migracoes; o de API cuida de endpoints e contratos; o de frontend cuida de componentes e estado. Pedido de uma zona pra outra passa pelo work graph.
E isso que faz um agente de vida longa acumular valor: um agente de seguranca que ja revisou 300 mudancas conhece o modelo de ameaca implicitamente.
Nenhum agente vaza pro contexto de outro. Dominio claro = memoria util acumulando no lugar certo.
Abrir uma tarefa em N ramos, rodar ao mesmo tempo e juntar os resultados. E o movimento que um loop nao faz.
A juncao e onde mora o perigo: um merge malfeito engole uma fonte em silencio, sem alarme.
Fan-out/fan-in e a primitiva de grafo que a Trilha 2 ja apontava como o limite honesto do loop.
A aresta escolhe o destino a partir do resultado do no: complexidade baixa vai pra resposta pronta, media vai pro agente de IA, alta ou arriscada escalona direto pro humano.
Existe tambem a aresta de "nao resolveu", que devolve pro caminho seguinte, e a de aprendizado, que volta pro classificador.
Roteamento por condicao e o que evita gastar agente caro em coisa simples e humano em coisa trivial.
A regra que a industria convergiu: codigo controla o roteamento previsivel; modelo cuida dos passos que exigem interpretacao ou julgamento.
Rotear com modelo o que um `if` resolve e caro, lento e nao deterministico — desperdicio puro.
Divisao de trabalho: codigo = previsivel, modelo = julgamento. Essa linha organiza todo o work graph.
🔭 Falhas, harness e observabilidade
O que voce compra junto com o grafo. Modos de falha que o loop nao tinha, o harness que vira runtime e a observabilidade sem a qual voce depura no escuro.
No fan-in, um ramo falha ou volta vazio e a juncao segue como se estivesse completa. O resultado parece bom e esta incompleto.
Esse tipo de erro nao dispara alarme nenhum — o painel continua limpo enquanto falta uma fonte inteira.
Juncao precisa checar cardinalidade: recebi os N que despachei? Sem essa checagem, o merge mente.
Duas arestas condicionais que se apontam: o revisor reprova, o escritor reescreve, o revisor reprova de novo, pra sempre.
E um ciclo sem progresso — a mesma falha estrutural de um loop sem condicao de parada, so que escondida dentro de um grafo.
Todo ciclo precisa de teto de voltas e de criterio de progresso. Sem os dois, o grafo nunca termina.
Um no passa adiante mais do que devia e o contexto limpo do no seguinte deixa de ser limpo.
O revisor que recebe o raciocinio do escritor volta a carimbar o trabalho — o mesmo problema do modulo 2.2, so que reintroduzido pelo grafo.
Vazamento de estado anula a vantagem principal do grafo: contexto separado por papel.
Declare explicitamente o que cada aresta carrega, com nome e formato.
Sem ele, cada mudanca em um no quebra o vizinho silenciosamente — o mesmo tipo de falha de integracao que qualquer API sem contrato sofre.
State schema e o contrato entre nos. E o documento que formaliza o que o modulo 4.1 chamou de "estado".
Grafo que roda em producao precisa sobreviver a falha no meio: retomar de onde parou, nao refazer no que ja terminou, e ser reproduzivel.
E a mesma coisa que orquestracao de dados resolve ha decadas — e e aqui que o grafo agentico herda um problema ja resolvido.
Durabilidade = checkpoint por no + idempotencia. Sem isso, todo erro custa o grafo inteiro de novo.
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?" esta enterrado num transcript; num grafo, o caminho percorrido e um dado que voce consulta.
Sem essa instrumentacao voce perde justamente a vantagem que motivou o grafo — visibilidade estruturada.