🚦 Check the three signals before migrating
There are exactly three signals that justify replacing a loop with a graph. No other reason counts — not "graphs seem more advanced," and not "everyone is doing it." If none of the three apply to your case, migrating will only cost you complexity without any payoff.
You need to run parts at the same time
Search three sources, generate two variations, check two independent criteria—work that doesn’t depend on one another and that a sequential loop can only do one at a time.
You need a reviewer who DOESN'T see how the work was done
In a single-context loop, the reviewer carries the same reasoning as the writer—and tends to approve their own work. Blind review requires a clean context: one that receives only the result, never the path to it.
The context is turning into a swamp
After many rounds in the same loop, the agent accumulates so much in its context that it loses the original instruction — it starts to “forget” the goal. This is a sign that a responsibility needs to move to another node, with its own context.
🆕 New here? Two words before you continue
- Baseline: the current version’s numbers (cost, time, quality), measured BEFORE any change — without them, you’ll never know whether a migration was worthwhile.
- Clean context: a node that receives only what it needs to do its job—never the reasoning or draft from whoever handled the previous step.
✓ Signs that authorize migration
- ✓There’s independent work that currently runs in a queue
- ✓You need a judgment that doesn't see the draft
- ✓The agent loses the original instruction after N rounds
✗ Signs the problem lies elsewhere
- ✗"It's slow" — diagnose first: it could be a bad prompt, not the architecture
- ✗"The verifier approves anything" — change the verifier, not the structure
- ✗"It looks more professional to have multiple agents" — fashion isn't engineering
Key concepts
Parallelism, blind reviewer, swamp
Trends don’t justify migrating
It’s almost always the real culprit
The foundation of blind review
📏 Measure before making changes
Before touching any code, write down three numbers from the current version: cost per execution (tokens or dollars), total time (from beginning to end) is a quality measure that you can verify yourself — for example, how many claims in the summary you manually checked and found correct, out of 10.
Migrating without a baseline is faith, not engineering. Without these three numbers, you’ll never know whether the graph delivered anything real or just traded one problem for another—one that looks better but costs more.
📊 The three numbers you need to write down
- Cost per execution — tokens consumed or dollars spent in a typical run
- Total time — from trigger to the finished final result
- Verifiable quality — a sample you check yourself (e.g., 10 claims, how many are correct)
🧪 Practical example: the baseline spreadsheet
Objective: record the three numbers for the current version (the loop) before migrating, and the same block afterward — to make a real comparison in topic 6.
// linha-de-base.json — preencha ANTES de migrar
{
"versao": "loop",
"data": "<aaaa-mm-dd>",
"custo_por_execucao_usd": <numero>,
"tempo_total_min": <numero>,
"qualidade": {
"amostra": 10,
"afirmacoes_corretas": <numero de 0 a 10>
},
"observacoes": "<o que voce notou rodando 3-5 vezes>"
}
// linha-de-base.json — preencha DEPOIS de migrar, MESMAS entradas
{
"versao": "grafo",
"data": "<aaaa-mm-dd>",
"custo_por_execucao_usd": <numero>,
"tempo_total_min": <numero>,
"qualidade": {
"amostra": 10,
"afirmacoes_corretas": <numero de 0 a 10>
},
"observacoes": "<o que mudou de verdade>"
}
How to verify: run each version 3 to 5 times with the same inputs before recording the results — one number could be luck. If you can't fill in the three fields for the current version right now, stop: measure first, migrate later.
💡 Practical tip
There is no perfect quality metric. The rule is simple: choose something you can check yourself without a new tool, and use the same criteria for both versions. Changing metrics midway invalidates the comparison.
Key concepts
Numbers BEFORE migrating
Cost, time, quality
No new tool
A single number could just be luck
✂️ Cut at the Context-Switch Points
Break the loop where the responsibility, a tool or the necessary context. Don't break it at arbitrary points—each cut needs to correspond to one of these three changes, or you've just created more nodes without adding clarity.
For the daily summary, that gives you three natural nodes: who search (needs the internet, produces notes), who writes (doesn’t need the internet, only the notes), who check it (needs the internet again to check facts, but must NOT see the draft being written).
What to look at: on the left, everything is piled into one context—search, raw HTML, draft, and review all jumbled together, turning on the same arrow. On the right, three separate boxes: the researcher has a range of cyan sources (can run in parallel), passes notes to the writer, who returns a draft to the reviewer. Only the red edge loops back — with a cap (max 2) and a label describing what it carries.
⚠️ Wrong cut: breaking things up because it “looks nice”
If you can’t point to which of the three things changed (responsibility, tool, context) in a cut, it’s artificial. A graph with artificial nodes is worse than the original loop: more prompts to write, more edges to maintain, and no real gain.
Key concepts
Responsibility, tool, context
Needs internet access; produces notes
Only needs the notes
Internet again, but with clean context
📜 Write the contract between nodes
Before writing any code, define what each edge carries — that’s the state schema, the exact format of the data passed from one node to the next. The researcher returns notes (not raw HTML — that’s the swamp coming back through the back door); the writer returns draft; the reviewer returns approved + critiques.
Also write down what explicitly does NOT pass: the writer’s reasoning doesn’t go to the reviewer. This isn’t a detail— it’s the difference between a real reviewer and one that just agrees with the writer.
🧪 Practical example: the migrated daily summary grafo.json
Objective: see the full contract — three nodes with their own configs and edges with conditions (quando), payload (passa) and return ceiling (max_voltas).
// grafo.json — resumo diario migrado (loop -> grafo)
{
"nos": {
"pesquisador": {
"modelo": "<modelo-rapido>",
"ferramentas": ["busca_web", "leitor_rss"],
"contexto_limpo": false,
"produz": "notas"
},
"escritor": {
"modelo": "<modelo-de-escrita>",
"ferramentas": [],
"contexto_limpo": false,
"recebe": "notas",
"produz": "rascunho"
},
"revisor": {
"modelo": "<modelo-rapido>",
"ferramentas": ["busca_web"],
"contexto_limpo": true,
"recebe": "rascunho",
"produz": "aprovado_ou_criticas"
}
},
"arestas": [
{ "de": "pesquisador", "para": "escritor", "passa": "notas" },
{ "de": "escritor", "para": "revisor", "passa": "rascunho" },
{
"de": "revisor", "para": "escritor",
"quando": "aprovado == false",
"passa": "criticas",
"max_voltas": 2
}
]
}
How to verify: if the reviewer receives any field
besides the text and the criteria (for example, the researcher's notes or the writer's attempt history), the context
contexto_limpo isn't delivering on its promise—and you won't gain anything from the migration,
because the bias of "approving your own work" is still there, just spread across two nodes.
💡 The contract is what remains after the hype fades
Graph frameworks come and go. What remains is the discipline of stating, in writing, what each edge carries and what it should never carry. If you write this down before the code, implementation becomes mechanical translation; if you skip this step, the code becomes the only place where the contract exists — and nobody reviews code with the contract in mind.
Key concepts
Exact data format on the edge
Too much raw data, and the swamp is back
Reasoning stays with whoever generated it
Write the contract first
🔁 Add the return edge with a limit
The reviewer sends a rejection back to the writer — this is the return edge, the cycle inside the graph. It needs to up to N passes is from a progress criteria: "two rounds without improvement = give up and let me know" is a criterion; "keep trying until it works" isn’t.
Without a cap, the bill is infinite—the same problem as any cycle without a stopping condition. Without a progress criterion, you pay for N rounds even when two would have been enough to know it won’t improve.
What to look at: notice there are two questions, not one. The first filters out cases where you didn't need to change anything (improve the verifier). Only if you reach the second question and answer "yes" does the glowing box — "build the graph" — authorize the migration. Any other path leads back to the loop or to a problem no graph can solve.
⚠️ Without a cap, the bill is infinite
Every return edge you draw needs to include, alongside it, the maximum number of iterations and the criterion that stops it before that maximum. If you can’t write those two things in a sentence, the edge isn’t ready for production yet.
Key concepts
Maximum N, never infinite
When to give up before the limit
It doesn’t get stuck: it notifies you and stops
The loop lives inside the graph
⚖️ Compare and Have the Courage to Backtrack
Run both — the loop and the graph — in parallel for a few days, with the same inputs. Fill out the same baseline spreadsheet from topic 2 again. If the graph didn't improve any of the three numbers, go back to the loop: you bought complexity without a payoff.
Acknowledging this is part of the work, not a failure. It’s what separates engineering from fashion: engineering measures and decides based on the numbers; fashion decides based on appearances and defends the decision afterward.
Check the three signals
Parallelism, a blind reviewer, or context swamp—without one of the three, don't migrate.
Measure the baseline
Cost, time, and verifiable quality, from the loop version, repeated 3-5x.
Cut at the right points
Responsibility, tool, or context—never an arbitrary cutoff.
Write the contract
What each edge carries—and what it explicitly does not carry.
Add the return edge with a cap
Maximum N iterations + a progress criterion, never “keep trying until it works.”
Compare and decide
Same inputs, same spreadsheet. If there’s no improvement in all three numbers, go back to the loop.
✓ Stick with the graph if
- ✓Total time dropped because of actual parallelism
- ✓The quality improved because the reviewer really couldn’t see the draft
- ✓The cost is worth the gain—you compared the two numbers side by side
✗ Go back to the loop if
- ✗The cost went up, and none of the other two numbers improved
- ✗The quality is the same, but now there are more pieces to maintain
- ✗You can't say what improved — a sign that you didn't measure properly
Quick check (nothing is blocked): You migrated a daily summary to a 3-node graph, but the cost per run doubled and quality stayed the same. What should you do?
Key concepts
A fair comparison requires this
Cost, time, quality — again
And part of the method
The number decides, not the appearance
📌 Module Summary
Next Module:
5.2 — Business and task graphs: model the multi-metric funnel and the backlog with dependencies and blockers.