🧭 Entenda "agentic": um agente com ferramentas e julgamento
"Agentic" descreve um jeito de usar um modelo, nao uma arquitetura. Voce descreve o objetivo, entrega um conjunto de ferramentas (busca, terminal, editor de arquivo) e deixa o modelo decidir, passo a passo, o que fazer a seguir. Nao ha um diagrama previo do caminho — o caminho e descoberto em tempo real, dentro da propria conversa.
🆕 Novo aqui? Duas palavras antes de seguir
- Julgamento do modelo: a decisao de "o que fazer agora" acontece dentro da cabeca do modelo, token a token — nao existe uma linha de codigo que diz "depois disso, faca aquilo".
- Teste de saida: uma condicao explicita e verificavel que diz quando o trabalho terminou (ex.: "os testes passaram"). Agentic puro raramente tem um; ele para quando o modelo "acha" que acabou.
Isso nao e defeito, e a caracteristica. Serve exatamente pra tarefa aberta e exploratoria — "investiga esse bug estranho", "le esse repositorio e me conta o que faz" — coisa que roda uma vez, onde voce nao sabe de antemao quais passos vai precisar. Tentar desenhar o fluxograma antes seria perda de tempo: voce nao sabe o fluxo ainda.
✓ Agentic serve bem quando
- ✓A tarefa e exploratoria — voce nao sabe os passos de antemao
- ✓Roda uma vez ou poucas vezes, sob supervisao humana
- ✓O custo de um passo errado e baixo e reversivel
✗ Agentic cobra caro quando
- ✗A tarefa se repete todo dia — voce reexplica o mesmo objetivo sempre
- ✗Precisa de garantia de "isso sempre vai acontecer nessa ordem"
- ✗Ninguem consegue prever o custo de tokens porque o caminho muda a cada rodada
Conceitos-chave
Mora na cabeca do modelo
Voce da, ele escolhe usar
Caminho descoberto na hora
Roda uma vez, exploratoria
🔁 Entenda "loop": o ciclo desenhado com teste de saida
No loop voce para de escrever prompt e comeca a projetar ciclo. Em vez de confiar que o modelo vai lembrar de verificar o proprio trabalho, voce escreve isso em codigo: descobrir → planejar → agir → verificar → parar. A estrutura sai da cabeca do modelo e vira algo que voce le, versiona e testa.
💡 A condicao de parada e o que muda tudo
Um loop so vira loop de verdade quando existe um teste de saida explicito — algo que voce pode rodar e que responde sim/nao: "os testes passaram", "o schema validou", "a nota do revisor e maior que 8". Sem esse teste, voce so tem um agentic com mais uma volta.
- •O modelo ainda decide o que fazer dentro de cada etapa, mas nao decide mais a ordem das etapas
- •Voce ganha reprodutibilidade: o mesmo processo roda igual na segunda-feira e na sexta
- •Voce paga com engenharia: alguem precisa escrever e manter esse ciclo
Serve pra tarefa repetivel com criterio de sucesso verificavel: gerar um relatorio toda manha, corrigir um bug ate os testes ficarem verdes, escrever um texto ate passar num checklist de qualidade. Se voce roda a mesma coisa mais de uma vez e sabe dizer quando ela deu certo, o loop e a estrutura certa.
Conceitos-chave
Descobrir/planejar/agir/verificar/parar
Condicao verificavel, nao "achismo"
Sai da cabeca, vira artefato
Roda toda vez, criterio claro
🕸️ Entenda "graph": loops compostos com arestas explicitas
Um grafo (nesse sentido de arquitetura de agentes) e varios loops ligados por arestas escritas antes de rodar. Cada no do grafo e, ele mesmo, um loop — com seu proprio modelo, suas proprias ferramentas, suas proprias permissoes e sua propria instrucao. O caminho entre os nos e o que o grafo acrescenta.
O que olhar: a caixa tracejada e nova, mas o conteudo de dentro nao e — cada no ainda tem sua propria voltinha (o "loop" escrito dentro dele). O grafo nao substitui o loop, ele compoe loops. E o que o proximo topico vai construir com um caso real.
Conceitos-chave
Cada no tem seu proprio ciclo
O caminho existe antes de rodar
Modelo, ferramentas e permissoes proprios por no
Grafo compoe, nao substitui, o loop
📰 Construa o mesmo caso nos tres formatos
O caso e um resumo diario de pesquisa: toda manha o sistema le algumas fontes sobre um tema, escreve um resumo de uma pagina, e confere se o resumo esta correto antes de mandar. Vamos construir esse mesmo objetivo tres vezes — e comparar o que acontece em cada versao.
Como loop unico sobrecarregado
Um agente faz tudo numa janela so: busca fontes, escreve, revisa.
Ele abre as fontes uma por uma — porque loop e sequencial por forma — e despeja o HTML bruto de cada uma no mesmo contexto (a janela de texto que o modelo esta "vendo" naquele momento). Quando chega na hora de revisar, esse contexto virou um pantano: HTML cru, prosa meio escrita e raciocinio anterior tudo boiando junto. E o pior: ele revisa no mesmo contexto onde escreveu — entao tende a carimbar o proprio trabalho.
Como grafo pequeno
Tres nos, estado fluindo entre eles, cada um com contexto proprio.
Pesquisador abre em N fontes em paralelo — isso e fan-out: abrir uma tarefa em varios ramos ao mesmo tempo. Ele entrega so as notas (nao o HTML cru) pro escritor, que recebe um contexto limpo — sem o lixo da busca, so o que importa pra escrever. O escritor entrega o rascunho pro revisor, que tambem tem contexto novo: ve so o texto e o criterio de qualidade, com uma aresta de volta "reprovado" pro escritor se nao passar.
O que olhar: tres coisas cruzam as arestas — notas, rascunho e criticas — e nenhuma delas e o HTML bruto das fontes. Isso e o que separa a versao grafo da versao loop unico: cada no recebe so o que precisa, nunca o transcript inteiro do no anterior. (Transcript = o historico completo de uma conversa/execucao, com todo o raciocinio intermediario — util pra depurar, pesado demais pra passar adiante como entrada.)
| Dimensao | agentic | loop | graph |
|---|---|---|---|
| Quem decide o proximo passo | o modelo, a cada token | o modelo, dentro de um ciclo fixo | o modelo, dentro de cada no; o roteamento entre nos e fixo |
| Onde mora a estrutura | na cabeca do modelo | em codigo, um ciclo | em codigo, um diagrama de nos e arestas |
| Paralelismo | nenhum nativo | nenhum — o loop e sequencial por forma | fan-out/fan-in de primeira classe |
| Contexto | uma janela so, cresce sem limite | uma janela por volta do ciclo | um contexto limpo por no |
| Como voce depura | lendo o transcript inteiro | lendo o transcript de cada volta | lendo o diagrama + o estado em cada aresta |
| Custo de manutencao | baixo (so o prompt) | medio (ciclo + condicao de parada) | alto (N prompts + state schema + roteamento) |
| Quando usar | tarefa aberta, roda uma vez | tarefa repetivel, um agente basta | tarefa repetivel que precisa de especializacao/paralelismo real |
Conceitos-chave
Daily brief nos tres formatos
Abrir 1 tarefa em N ramos
Cada no ve so o que precisa
Reprovado leva de volta ao escritor
✨ Saiba o que o grafo da de genuinamente novo
Sao tres coisas concretas, nao uma vibe de "mais avancado". Primeiro: nos paralelos especializados com contextos limpos e separados — o pesquisador nao carrega o vocabulario de revisor, o revisor nao carrega o ruido da busca. Segundo: fan-out e fan-in como movimento de primeira classe — abrir uma tarefa em N ramos, rodar ao mesmo tempo, juntar o resultado. Terceiro: fluxo de controle explicito e auditavel — o caminho e um diagrama que voce le, nao algo que voce reconstroi lendo um transcript de 40 mil tokens.
O que olhar: os dois lados resolvem "fazer mais coisa" de jeitos opostos. O loop cresce pra baixo — mais voltas no mesmo no. O grafo cresce pra fora — mais nos rodando ao mesmo tempo. Nao da pra fazer um fan-out real dentro de um loop unico; ele so sabe repetir, nao dividir.
Conceitos-chave
Contexto limpo e separado
Juntar os N ramos de volta
Diagrama que se le, nao se reconstroi
Grafo cresce pra fora, loop pra baixo
💸 Saiba o que o grafo cobra
Nada disso e de graca. Voce passa a manter tres prompts em vez de um — cada no tem sua propria instrucao, e as tres precisam evoluir juntas sem quebrar as arestas entre elas. Voce precisa definir um state schema: o formato exato do que o pesquisador entrega pro escritor, do que o escritor entrega pro revisor. Sem esse contrato escrito, os nos comecam a se desentender sobre o que "notas" ou "rascunho" significam.
⚠️ Modos de falha que so existem no grafo
- Merge que engole uma fonte em silencio — o fan-in junta 5 ramos, um falhou, e ninguem percebeu que faltou uma fonte no resumo final.
- Roteamento que fica indo e voltando pra sempre — a aresta "reprovado" manda de volta pro escritor, que escreve de novo, que e reprovado de novo, sem limite de tentativas.
- Estado que vaza de um no pro outro — o contexto que deveria estar limpo carrega lixo do no anterior porque o state schema nao foi respeitado.
✓ A sobrecarga compra qualidade quando
- ✓A tarefa roda todo dia — o custo fixo de montar o grafo se paga em repeticoes
- ✓Existe paralelismo real a explorar (N fontes, N ramos)
- ✓Especializar cada no de fato melhora o resultado (revisor com criterio proprio)
✗ A sobrecarga e imposto puro quando
- ✗A tarefa roda uma vez — voce nunca recupera o custo de montar tres prompts
- ✗Nao ha nada pra paralelizar — e um processo genuinamente sequencial
- ✗Um unico no, com todas as ferramentas e todas as instrucoes — isso e loop reinventado; a estrutura de grafo nao esta fazendo nada
🧪 Exemplo pratico: grafo degenerado x grafo de verdade
Objetivo: comparar o mesmo grafo.json do daily brief em dois formatos — o "grafo de um no so" (nome de grafo, corpo de loop) e o de tres nos (grafo de verdade) — e ver a diferenca no proprio arquivo.
// grafo.json — VERSAO DEGENERADA (1 no, todas as ferramentas, todas as instrucoes)
{
"nodes": [
{ "id": "faz-tudo", "model": "<seu-modelo>",
"tools": ["buscar", "escrever", "revisar"],
"prompt": "Busque as fontes, escreva o resumo e revise ate ficar bom." }
],
"edges": []
}
// isto NAO e um grafo funcional — e um loop com nome de grafo.
// zero arestas = zero coisa que a estrutura de grafo esta fazendo.
// grafo.json — VERSAO DE TRES NOS (grafo de verdade)
{
"nodes": [
{ "id": "pesquisador", "model": "<modelo-rapido>", "tools": ["buscar"],
"prompt": "Para cada fonte em paralelo, extraia so os fatos relevantes ao tema." },
{ "id": "escritor", "model": "<modelo-de-escrita>", "tools": [],
"prompt": "Com base APENAS nas notas recebidas, escreva um resumo de 1 pagina." },
{ "id": "revisor", "model": "<modelo-critico>", "tools": [],
"prompt": "Compare o rascunho com as notas originais. Aprove ou reprove com criticas especificas." }
],
"edges": [
{ "from": "pesquisador", "to": "escritor", "carrega": "notas" },
{ "from": "escritor", "to": "revisor", "carrega": "rascunho" },
{ "from": "revisor", "to": "escritor", "quando": "reprovado", "carrega": "criticas", "limite_voltas": 2 }
]
}
Como verificar: conte os edges.
Se a versao "grafo" do seu projeto tiver zero arestas ou um unico no com todas as ferramentas, e a versao degenerada —
um loop disfarcado. Se tiver arestas com carrega definido (o que passa de um no pro outro),
e um grafo de verdade.
Teste de vies: peca pro Claude Code julgar uma tarefa sua
e dizer se ela merece agentic, loop ou graph — exigindo que ele justifique por que as outras duas nao servem.
Se ele responder "grafo" pra uma tarefa que roda <uma vez so>, isso e viés de hype.
Peca o custo de manutencao: quantos prompts, qual state schema, qual modo de falha novo ele esta assumindo.
Checagem rapida (nao bloqueia nada): voce tem um grafo com UM unico no, que tem todas as ferramentas e todas as instrucoes do processo. O que isso realmente e?
Conceitos-chave
O contrato entre nos
Um por no, evoluindo juntos
Merge, loop de roteamento, vazamento
1 no com tudo = loop disfarcado
📌 Resumo do Modulo
Proximo Modulo:
3.3 — Mito x fato: separando o que o graph engineering promete do que ele de fato entrega.