🔵 Fundamentos: o grafo

O no e uma coisa do seu mundo: uma pessoa, uma tarefa, um passo do processo, um agente de IA. Em codigo aparece como n ou node.

Escolher o que vira no e a primeira decisao de modelagem — e a que mais erra. Se o no e grande demais, o grafo nao ajuda em nada; se e pequeno demais, voce afoga em detalhe.

No = substantivo. Um no tem identidade (da pra apontar pra ele) e pode carregar dados (rotulo, custo, dono, estado).

A aresta e a relacao entre dois nos. Em codigo, e ou edge. “Depende de”, “vira”, “conhece”, “passa o resultado pra”.

Num sistema de agentes, a aresta e onde mora a decisao: “se aprovou, vai pra ca; se reprovou, volta pra la”. E o valor esta mais nas arestas do que nos nos.

Aresta = verbo. Ela pode ter tipo (aresta tipada), direcao e peso. Grafo sem aresta e so uma lista de coisas soltas.

Num grafo dirigido, a aresta tem seta: vai de A pra B e nao volta por ali. Num grafo nao-dirigido, a ligacao vale nos dois sentidos (amizade, por exemplo).

Todo fluxo de trabalho de agente e dirigido: o pesquisador entrega pro escritor, nao o contrario. A direcao e o que da ordem ao sistema.

Dirigido = seta = ordem. Se voce quer voltar, isso e outra aresta (e ela pode ter regra propria: “so volta se reprovou”).

Um numero pendurado na aresta: minutos, reais, tokens, probabilidade, distancia. E o que transforma “desenho” em “estrutura calculavel”.

Sem peso voce so sabe se da pra ir; com peso voce sabe qual caminho vale a pena. E ai entram busca e otimizacao.

Peso pode ser custo (minimizar) ou ganho (maximizar). Num grafo de agentes o peso costuma ser latencia, custo em token ou confianca.

Um caminho que sai de um no e volta pra ele. Se um grafo dirigido nao tem nenhum ciclo, ele e um DAG (grafo dirigido aciclico).

Este e o ponto de virada do curso inteiro: um loop e um ciclo. Loop e o grafo mais simples que existe — um no com uma aresta que volta pra ele mesmo.

DAG = sem volta = termina sozinho. Com ciclo = pode repetir = precisa de condicao de parada, senao roda pra sempre.

Lista = cada item tem um proximo. Arvore = cada no tem um pai so, sem ciclo. Grafo = qualquer coisa se liga a qualquer coisa. Lista e arvore sao casos particulares de grafo.

Muita gente desenha uma arvore (epic → story → task) e acha que resolveu — ate aparecer a dependencia cruzada entre dois ramos. Ali a arvore virou grafo.

Se existe dependencia cruzada, e grafo. Nao force uma arvore num problema que e grafo — voce so vai esconder a dependencia real.

Acordar → levantar → escovar os dentes → cafe. Cada etapa e um no; o tempo entre elas e o peso da aresta (2 min, 5 min, 3 min).

E o menor exemplo que ja mostra tudo: nos, arestas dirigidas, pesos em minutos — e um caminho alternativo (alguem traz o cafe na cama) que pula um no.

Modelar = escolher o que e no e o que e peso. Caminho alternativo = outra aresta, nao outro grafo.

Cada pessoa e um no; cada relacao e uma aresta com peso (amizade, trabalho, temas em comum). “Voce esta a 3 conexoes do Lucas” = 3 arestas de distancia.

E o exemplo que mostra que o algoritmo navega o grafo pra decidir o que te mostrar. A mesma ideia vale pro seu agente navegando documentacao.

Distancia em arestas = “graus de separacao”. Peso da aresta = forca do laco. Recomendacao = travessia com criterio.

Campanha → trafego → signup → ativacao → assinante → churn → LTV. Nos sao estados do cliente; arestas sao taxas de conversao.

E o exemplo que expoe o problema central do curso: otimizar uma aresta (baixar o CAC) pode piorar outra (subir o churn) sem que ninguem perceba.

Uma metrica nunca basta. O grafo e o que te deixa ver o efeito colateral em vez de so o efeito principal.

Epic contem stories, story contem tasks, task contem subtasks. Parece arvore — ate uma story depender de outra. Ai virou grafo.

E assim que um PM decide quantas pessoas (ou quantos agentes) podem trabalhar em paralelo: o grafo diz quais ramos nao se bloqueiam.

Aresta de dependencia = bloqueio. Ramos independentes = paralelismo possivel. Dividir tarefa e desenhar o grafo pra nao travar ninguem.

Em vez de largar dezenas de arquivos .md soltos em pastas, voce liga os documentos entre si e diz o tipo da ligacao (“pre-requisito de”, “contradiz”, “detalha”).

O agente para de ler tudo e passa a navegar: entra pelo no certo e segue as arestas relevantes. Menos contexto queimado, mais precisao.

Atencao: isso e grafo de conhecimento, primo — mas nao sinonimo — de graph engineering. A Trilha 3 separa os dois.

Modulo A importa B, B importa C. O npm, o make, o seu CI — todos montam um grafo dirigido e decidem a ordem a partir dele.

E o exemplo mais proximo do que voce vai fazer com agentes: o build ja resolve “o que roda em paralelo” e “o que espera” exatamente como um work graph.

Dependencia circular = ciclo = erro de build. A ferramenta detecta ciclo — o seu grafo de agentes vai precisar detectar tambem.

Em largura (BFS) voce visita todos os vizinhos antes de descer; em profundidade (DFS) voce desce um caminho ate o fim antes de voltar.

E a mesma escolha que voce faz com agentes: varrer muitas opcoes raso (largura) ou perseguir uma linha ate o fim (profundidade).

Largura acha o mais proximo primeiro. Profundidade acha uma resposta rapido. Marque quem ja visitou — senao ciclo vira loop infinito.

Achar a rota de menor custo entre dois nos somando os pesos das arestas. O caminho com menos saltos nem sempre e o mais barato.

Num grafo de agentes o “custo” e token, latencia ou risco. Escolher rota e escolher quanto voce vai gastar pra chegar no mesmo resultado.

Menos arestas ≠ mais barato. Se o peso muda com o tempo (latencia de API), o caminho otimo muda junto.

Uma fila valida de execucao num DAG: ninguem roda antes de quem ele depende. E o que o make calcula.

E literalmente o escalonador do seu grafo de agentes: ele diz o que ja pode disparar agora e o que tem que esperar.

So existe ordem topologica se nao houver ciclo. Se o algoritmo nao consegue ordenar, ele achou uma dependencia circular.

Quantos nos estao prontos ao mesmo tempo. Se dois ramos nao se bloqueiam, cabem dois trabalhadores — dois devs ou dois agentes.

E como voce dimensiona a frota: nao adianta disparar 20 agentes se o grafo so libera 3 nos por vez.

Paralelismo e propriedade do grafo, nao do seu entusiasmo. Quebrar tarefa em partes que nao se bloqueiam aumenta a largura.

A espera B, B espera A: ninguem anda. Num grafo de agentes isso vira roteamento que fica indo e voltando entre dois nos pra sempre.

E um dos modos de falha novos que o grafo traz e o loop nao tinha. Precisa de teto de repeticoes e de deteccao explicita.

Todo ciclo precisa de saida: limite de voltas, criterio de progresso ou aprovacao humana. Ciclo sem saida = fatura infinita.

Na pratica, um dicionario: para cada no, a lista de vizinhos. {"pesquisa": ["escrita"], "escrita": ["revisao"]}.

Porque e assim que voce vai escrever seu grafo de agentes em JSON/YAML e entregar pro orquestrador — sem framework nenhum se nao quiser.

Lista de adjacencia serve pra quase tudo. Guarde tambem os dados do no (modelo, ferramentas, prompt) — e isso que vira um grafo agentico.