Agentic workflows: a field guide from building one

1. Routing by engine, not by what the job needed

   What broke

   A policy sent every research worker to the cheapest engine. That engine had no mail or drive connector, so the workers improvised with a mounted folder and a token they found on disk.

   The fix

   Route by capability first: which engines are logged in and have every connector the node needs, connected right now. Then apply the budget. And a preflight on Run that blocks with the exact gap and two buttons: fix it in a terminal, or use another engine.

2. Budgets counted the cache

   What broke

   Every turn, an agent re-reads its own context at a fraction of the price. The meter added those cache reads to the ceiling, so a worker with 110,000 tokens of real input "spent" 1.5 million in twenty turns and was stopped.

   The fix

   Meter input, output and cache writes. Show cache reads beside the number, never inside it.

3. The supervisor's clock never reset

   What broke

   A watcher stops a node that has been silent for three minutes and resumes it with a nudge. Its clock was only reset by new text, so each resumed node was stopped again eleven seconds later. One node lost four attempts in forty-five seconds.

   The fix

   Restart the clock for every process you start, and give a correction a full window.

4. A long write looked like silence

   What broke

   The strongest model sat down to write a 30 KB file in one go. The CLI only reports whole messages, so nothing arrived for three minutes and the watcher killed it mid-write. Four times in a row.

   The fix

   Ask the CLI for partial messages, treat the chunks as progress, and leave them out of the log.

5. Headless agents cannot ask

   What broke

   One CLI refuses a command it is unsure about by cancelling the whole turn. Another returns a sandbox error and tries variations. Neither can ask a person, so the run failed silently or burned turns.

   The fix

   An approval hub: the node pauses, the person gets a desktop notification with the exact command and Allow once, Deny or Allow for this run, and the node's own session resumes with the answer. The clock stops while it waits.

6. Checkers with no access hollowed the answer

   What broke

   Verifiers got a summary, no tools, and a wall between them and the worker. So they rewrote every claim as "unverified" and dropped whole sections. The merge then merged the verdicts, not the findings. The final document was 60 hedges.

   The fix

   A checker gets the same access as its worker, on another engine or model, reads the whole output, and may say unchecked: the claim stands as written. The merge carries unchecked claims through word for word, and the final writer reads each worker's own output beside the merged notes.

7. "No limit" read as "nothing"

   What broke

   Setting a budget to 0 meant no ceiling to the runner and "you have 0 tokens and 0 minutes" to the brief. One model ignored it. Another answered in twenty seconds that it had been given nothing and stopped.

   The fix

   Never print a number that means something else. Say "no ceiling".

8. Nobody asked the person anything

   What broke

   The goal named no systems, no people, no decisions in flight. The agents guessed. Afterwards the owner typed twelve categories of context by hand that a five-minute interview would have found.

   The fix

   An interview before the first run: rounds of questions with options and a recommended answer, facts looked up rather than asked, answers saved with the graph and threaded into every brief. And mid-run, a node that needs a fact asks: the supervisor answers from what is known, else the person does.

9. Instruction files from above the folder

   What broke

   Coding CLIs load instruction files from every folder above the one they run in. A node running under a home folder inherited the owner's personal rules, and the run's own record, which the checkers were meant never to see.

   The fix

   Per-node settings that exclude instruction files above the workspace, and never name your run record after a file the CLI treats as instructions.

10. Three CLIs, three sets of habits

    What broke

    One loads a 16 KB memory block into every session. One reports no cost at all. One cancels on the first refusal. One loads the user's own settings and hooks into every node.

    The fix

    One adapter per engine that knows its flags, a separate home folder for the one that needs it, and a real probe of each CLI on the machine before trusting a flag you read about.

• Capability first, budget second. An engine that cannot reach what the node needs is out before cost is considered.
• A checker gets its worker's access, on a different engine where one has it, else a different model. Isolation stays: no worker chat, no run record.
• Mechanical steps go to code, not a model. Running the tests, merging a branch, counting inputs. No tokens, no opinions.
• Mechanically blocked beats told. A deny rule on credential folders, a sandbox, a refused run. "Please do not" is a guardrail, and guardrails bend.

• $10.31 to $3.92control to treatment 3, same prompts
• 16 to 0failed or partial node attempts
• 60 to 0times the final document said "unverified"
• 1 to 5 of 6facts the owner needed that reached the document

Where the money goes

• Calls, model size, and how much each call reads. Every session loads its tools and instructions before your prompt. A session with no connectors loads 27 tools; one that inherits every connector loads 248, and re-reads that list on every turn.
• Cache reads are the quiet multiplier. In the control they were five and a half times the real tokens. Cheap per token, but they are what a long-running node mostly does.
• Reasoning effort is a bigger lever than model tier. In a 172-node qualification on the cheapest models, every node finished. The web-heavy graphs cost up to $5 at one CLI's default effort and $0.15 to $0.40 at low effort, with the same outcomes.
• Put mechanical steps on small models or on code. Splitting a list, counting inputs, running tests. Save the strong model for the final answer and for judgement.

Three kinds of loop, and what the research says

• Try, check, adjust, again. One agent makes something, a separate check scores it, the agent fixes what the check found, and it goes round until the check passes. Anthropic calls this the evaluator-optimiser workflow and recommends it when the pass mark is clear and a critique actually improves the next attempt (Building effective agents). It is Rigging's Loop shape and its fix rounds on a failing test.
• Critique yourself. The same model writes, critiques its own draft and rewrites. Self-Refine reported about 20 points better on average across seven tasks than a single pass (Madaan et al., 2023), and the gains fade after two or three rounds. Cheap, and only as good as the model's eye for its own faults.
• Remember the lesson. After a failed attempt, the agent writes down in words what went wrong and reads that note before the next try. Reflexion took a coding benchmark from 80% to 91% that way (Shinn et al., 2023). Rigging's lessons file does this across runs: every run ends by writing what failed and the one rule that would have prevented it, and every later brief loads it.

Why loops must have limits

• Cap the rounds. Two or three. Self-critique gains fade after that, and a loop with no cap is a bill with no ceiling. Every loop in Rigging has a number: fix rounds, supervisor strikes, interview rounds, questions per node.
• Stop on the check, not on the agent's opinion. The thermometer, the test suite, the money that landed. If the only judge is the agent, it will bend the rules to hit its number.
• Stop when the gain is small. If round three changed almost nothing from round two, you are paying for noise.
• A person before anything irreversible. Sending, publishing, merging, spending. A gate, mechanically enforced, not a sentence in the prompt.

A loop that improves the thing that tests the thing

This is the loop I run on Rigging itself, and it is the one most worth copying. It runs at most twice per round.

1. Run, and keep the receipts

   What

   Every node's prompts, outputs, denials, questions and costs stay on disk.

2. QA reads the output, not the story

   What

   A separate agent on a different model reads the receipts and the code and says what is wrong, ranked. A person checks the highest-ranked findings against the code before anything is commissioned.

3. Learn: one improvement and one new test

   What

   An agent reads the QA report and the lessons file and proposes a single change plus the test that would prove it. Not a list of twenty. One, with a test.

4. Build and run the new test

   What

   The change is built in its own branch with the test in it; the test runs as code, not as an opinion. Green or it does not merge.

5. A person tastes it, then loop at most once more

   What

   The owner uses the thing. If it is still wrong, round two with a new finding. If it is right, stop. Never a third round on the same finding: that is a sign the finding was wrong, not the fix.

An example product loop, described, not built

A workflow I have not run yet but can draw, from a feature request to paying customers, with every loop capped and every irreversible step behind a person.

• What flows. The call notes land in a repository. A research fan-out reads them with the market, each finding checked. A coding worker builds the smallest thing that could be true, with its tests run as code. The product manager tastes it at a gate. A capped loop builds it out. A discovery loop finds prospects until finds dry up or the cap hits. Nothing is sent until a person says yes. Replies come back, an agent reads them and asks the product manager what it cannot settle, with a limit on questions. A person reviews. Then it restarts from the build step with the new information, at most twice, before someone writes a fresh brief.
• Why it would work. Every irreversible step has a gate. Every loop has a cap. Every check that can be code is code. And the person is asked questions, not handed hedges.
• Why I have not built it yet. Sending on someone's behalf and reading replies are the two steps where a mistake is public. Those need the mechanical blocks first: a sender that cannot run without a yes, and a reader that cannot write back.

• Access comes first. Check every login and connector before a single token is spent, and block the run with the exact gap when one is missing.
• Interview before you run. The person knows which systems hold the truth, who to ask, and what the reader must be able to do afterwards. Agents cannot guess that, and the questions are cheap.
• Cut the job by what the reader needs, not by where to look. Five source-shaped workers produced a document organised by folder. Eleven reader-shaped sections was what the owner wrote by hand.
• A checker without access destroys information. Give it the worker's access and an honest third verdict: unchecked.
• Say what a limit means. Never print a number a model can misread.
• Make a human easy to reach. A notification with the command and three buttons beat every guardrail sentence I wrote.
• Stream progress, not just results. A watcher that cannot see a long write will kill it.
• End with the thing, not a report about the thing. For a document, a link that opens it. For code, the branch, the diff, a terminal in the worktree, the tests re-run, and a merge button behind a gate.
• Keep the receipts. Every prompt, output, denial, question and cost per node. The post-mortem that found all of the above took an hour because they existed.
• What still goes wrong. A sandboxed node cannot always reach a login kept in the keychain. A merge with many checked inputs hits its input cap. An answer given mid-run reaches the node that asked, not its checker. All open, all written down.

Shape names follow Anatoli Kopadze's "Graph Engineering explained"; the wording, the harness and the numbers are mine. Rigging is private for now. If you want to compare notes on any of this, the message form on the home page reaches me.