AgentLu
← Learn

Workflows & Agent Loops

16 min read

There are two ways to get work out of a model, and they fail in opposite directions. In the first, you decide the steps: draft, check, revise, stop. In the second, you hand the agent a goal and a set of tools and let it choose what to do next. The first is predictable, cheap and testable; the second handles tasks you cannot write down in advance.

Most real agents are both, layered: a fixed pipeline where you know the steps, with a bounded agent loop inside the step where you do not. Knowing which layer you are in - and being able to say why a run stopped - is most of the craft.

This chapter is about that: how order is decided, how loops end, what a budget is for, and how to tell whether a workflow with more agents in it is better or just more expensive. The exercises make every one of those visible, because a workflow you cannot inspect is a black box with extra steps.

A workflow is a decision about order

A workflow is a fixed sequence with a reason: retrieve, then answer, then cite. Each step has an input, an output and a condition for continuing. Because the order lives in your code rather than in the model's head, you get three things for free - the cost is predictable, the failure is reproducible, and you can test each step on its own.

That last one is the giveaway. If you cannot test a step without a model, you have not separated the workflow from the model's judgement. The writing workflow in the exercises is a good example: the drafting is a model call, but the check that decides whether to continue is a plain function with a rubric. The loop is code; the taste is the model's.

The cost of a fixed order is that it cannot adapt. If the request needs something the sequence does not contain, a predefined workflow will do the wrong thing confidently. That is the trade: you choose the order when you know the steps, and you pay for it in flexibility - which is fine, as long as you know that is what you are paying.

The agent that picks its next action

The alternative is a loop with a model in it: look at the state of the world, decide which tool to call next, call it, look again. This is what people mean by an *agent*, and it is the right shape when the steps depend on what you find. A support triage agent does not know in advance whether the answer is a refund policy or a password reset - it finds out by looking.

The price is real. Every step is a model call, so cost and latency grow with the number of steps, and none of them are known in advance. Worse, the failure modes multiply: the model can pick a tool that does not exist, pass arguments the tool rejects, loop forever between two calls, or decide it is finished long before it is.

So the honest way to read the two approaches is not 'dynamic is smarter'. It is: dynamic when the steps are unknown, fixed when they are known, and a fixed pipeline with a bounded dynamic step inside it for everything in between. The exercises contain both shapes, and the difference shows up in the trace.

// A predefined workflow: the order is in the code.
const draft = await llm({ system: DRAFT_PROMPT, user: brief });
const verdict = await callTool("checkDraft", { draft: draft.content, brief });
if (!verdict.ok) draft = await llm({ system: REVISE_PROMPT, user: issues(verdict) });

// A dynamic loop: the model chooses, so you bound it.
let step = 0;
while (step < MAX_STEPS && !done) {
  const decision = await llm({ system: ROUTER_PROMPT, user: state, json: true });
  const result = await callTool(decision.tool, decision.args);
  state = observe(state, result);   // "done" comes from the world, not the model
  step += 1;
}javascript

The same job, two shapes. Top: the order is yours. Bottom: the order is the model's, so the loop has to be bounded.

Routing and branching

A branch is a decision with a small number of answers: this is a billing question, so it goes to billing; this is a password reset, so it goes to the reset flow; this is neither, so a human sees it. Routing is the same idea with a model in the decision, and it is the cheapest place in an agent to spend a model call - one call replaces a whole misdirected conversation.

Two rules keep branching honest. First, the branch must be *observable*: the run has to say which branch it took and why, or nobody can debug a misroute. Second, every branch needs a default - the fallback is not 'do nothing', it is 'hand it to a human with the context attached'. A router with no default is a system that silently drops the requests it does not recognise.

The front desk and support triage exercises are both branch-first designs: classify, then act, then escalate if the classification is not confident enough. They are also a good place to notice how much of the value comes from the refusal path - the correct answer to an unknown request is rarely a guess.

Every loop needs a reason to stop

A loop that ends when the work is good is not a stopping condition, it is a wish. Loops end for exactly three reasons, and a workflow should be able to name which one: the goal was reached, the budget ran out, or the work was handed to somebody else. 'It finished' tells a reader nothing.

The budget is the part people skip. A loop whose length depends on the data is a loop that can run forever - the cupboard assistant in the exercises may find a suitable item on the first candidate or on the fourth, and on a request nothing satisfies it will look at every one of them. MAX_CHECKS is not a performance tweak; it is the promise that the loop always ends, and the reason the stop message can say something useful.

The same is true of the platform's own limits: a run may make twelve tool calls and six model calls, and a loop that keeps asking hits a wall with a clear error. Those numbers are budgets in the same sense - and the exercise that compares approaches exists to make you notice what you spend.

When the budget runs out, say so. A workflow that quietly returns its best attempt so far, without mentioning that it never converged, is worse than one that fails loudly: the second is debuggable, and the first is a lie.

let chosen = null;
let checked = 0;

while (checked < MAX_CHECKS && !chosen) {        // the budget is the bound
  const item = await callTool("inspectItem", { id: listed.items[checked].id });
  checked += 1;
  const reason = rejectReason(item, need);      // a reason, not a bare no
  if (reason) { rejected.push(item.id + " - " + reason); continue; }
  chosen = item;
}

const stoppedBecause = chosen
  ? "found a suitable item after " + checked + " check(s)"
  : "reached the " + MAX_CHECKS + "-candidate limit with nothing suitable";javascript

The loop from the cupboard assistant. Bounded, with a reason per candidate and a stop reason that distinguishes the two endings.

Building the writing workflow, step by step

The writing workflow drafts, checks the draft against a rubric, revises what failed, and stops for a reason. The starter drafts once, checks once, and ignores the verdict - so the shape is visible and the loop is missing.

1. Run the starter and read the check

The checker is a plain function with a rubric: word count, whether the draft is about the brief, and a banned-phrase list. The starter's first draft fails on the length, the check records the word count, and nothing else happens - the draft is returned as if the check had passed.

2. Add the loop, and bound it

Check, then revise, then check again - while a counter is below MAX_REVISIONS. The counter is not decoration: it is the difference between a workflow and a hang. Note that the loop checks before it revises, so a draft that already passes costs nothing.

let revisions = 0;
let verdict = null;

while (revisions <= MAX_REVISIONS) {
  verdict = await callTool("checkDraft", { draft: current, brief: input });
  if (verdict.ok) break;
  if (revisions === MAX_REVISIONS) break;
  current = (await llm({ system: REVISE_PROMPT, user: issues(verdict) })).content;
  revisions += 1;
}javascript

3. Hand the model the complaints, not the draft

The revision prompt gets the brief, the draft and the exact issues the checker found. A blind 'make it better' throws away work that already passed and often breaks something that was fine; naming the two problems makes the model's job small and the improvement visible.

4. Say why it stopped

Two endings, two messages: 'the checker passed after 1 revision(s)' or 'the revision limit was reached with 2 issue(s) left'. The card draws them differently, and the grader checks that the run knows which one happened. This is the single most useful line in the whole workflow.

5. Watch the steps add up

With the tool trace open, the run reads understand, model, check, model, check, stop. Two model calls, two checks, one revision - and every intermediate result is on the card. That trace is what makes the difference between 'the answer looks fine' and 'the answer is fine, and here is how it got there'.

What a specialist team costs

'Use multiple agents' is a cost, not an improvement. Every handoff is another model call, another place for the work to go wrong, and another piece of state to keep straight. The only honest reason to add a specialist is that the handoff buys quality you can *measure* - and measuring it means scoring both approaches the same way.

That is what the advanced exercise does. One generalist answers from everything it retrieved, in a single call, unverified. A team of three - researcher, summariser, verifier - picks its sources, writes from those only, and removes every sentence the sources do not support. Both answers are then scored by one rule, against one ground truth, and the card reports quality next to calls.

The result is usually the same story in miniature: the team scores higher and costs more, and the interesting question is whether the difference is worth the price for this task. For a question about a two-paragraph policy, one careful call with the right passage beats three agents agreeing with each other. For a fifty-page report with figures that must be checked, the verifier is the whole point.

There is a trap worth naming: the measurement is blunt, and blunt measurements miss things. In the exercise, a summariser that covers only half the question can still score full precision, because every sentence it wrote is supported. Precision is not completeness - so the extension asks you to add the second measurement, and to notice that a number which cannot see a wrong answer is worse than no number, because it is trusted.

Mistakes worth catching early

What goes wrongWhat it looks likeWhat to do instead
A loop with no boundA checker that never passes, and a run that spends the whole wall-clock budget.A counter and a limit, whatever the checker says.
A loop with no stop reason'Done' after three revisions that fixed nothing, and no way to tell.Record which ending happened, and print it.
Revising everythingA blind rewrite that fixes the named issue and breaks something that passed.Hand the model the exact issues the checker found.
Deciding by model when code would doA model call to answer a question a rubric can answer, at ten times the cost.Keep the stopping condition deterministic, and let the model write.
A branch with no defaultUnrecognised requests vanish, or get the nearest wrong answer.Every branch ends somewhere, and the default escalates with context.
Adding agents to look sophisticatedThree handoffs, more cost, and a quality score nobody measured.Run both, score both the same way, and report the trade-off.

Debugging a workflow

  • Read the trace before the answer. The steps, in order, tell you which decision went wrong; the reply only tells you that one did.
  • When a loop runs too long, log the counter and the condition. Nine times out of ten the condition is never updated, or updated in the wrong branch.
  • When a loop stops too early, check what 'done' means. A checker that passes a bad draft is a rubric problem, not a loop problem.
  • When a workflow works once and not twice, look at what it carries between runs: a counter or a cache that outlives the run is the usual culprit.
  • When a branch fires wrongly, print the classification and its confidence. Routing bugs are almost always ambiguity bugs.
  • When you add a specialist, measure before and after. A handoff that improves nothing is a handoff to delete.
  • Keep the budget in one place, named, at the top of the file. A limit buried inside a condition is a limit nobody can tune.