The whole distinction is: who decides the order of operations? A chatbot answers once. A workflow follows a path you wrote in advance. An agent decides its own path as it goes. Everything else in this primer — tools, memory, loops, failure modes — follows from that one question.
Figure 1
Chatbot, workflow, agent
Three systems, drawn to the same scale. Watch what moves as you go left to right: not the intelligence, but the location of control.
Nothing acts. Text goes in, text comes out. It cannot read a file or send an email, so it cannot be wrong about the world — only about words.
You decide the order. The model is smart at each step, but it never chooses what happens next. Same input, same route, every time.
The model decides the order. It picks a tool, sees the result, judges whether the goal is met, and goes again. You wrote the tools and the goal — not the route.
Walking someone through this
1
Start at the left. Ask what this system can break. Nothing — it only produces text. Most people's mental image of AI stops here, which is why the risks of the third panel come as a surprise.
2
Middle panel: point at the dashed box. Somebody sat down and wrote that sequence. The model is doing intelligent work inside each step and no thinking at all about which step comes next. This is where most useful business automation actually lives.
3
Right panel: trace the loop with your finger. Model → tool → result → "done?" → back to the model. That return arrow is the entire difference. Ask: if it can loop, who decides when it stops?
4
Then the closing question, which is the one that matters commercially: which of these does the job you actually have? Most people reach for panel three and needed panel two.
Workflows and agents are not the same thing
The vocabulary is genuinely inconsistent in the wild — worth naming
Anthropic treats both as agentic systems but draws a hard architectural line between them. Workflows are systems where models and tools are orchestrated through predefined code paths. Agents are systems where models dynamically direct their own processes and tool usage, keeping control over how they accomplish the task.
Most vendor and course material collapses this distinction, because "we built an agent" sells better than "we built a three-step script with a model in it." When someone tells you they have an agent, the useful question is not what it does but who chose the order. If the answer is a developer, it's a workflow — with all the predictability that implies.
Most vendor and course material collapses this distinction, because "we built an agent" sells better than "we built a three-step script with a model in it." When someone tells you they have an agent, the useful question is not what it does but who chose the order. If the answer is a developer, it's a workflow — with all the predictability that implies.
Workflow
Path fixed in code before it runs
Same input, same route
Cost and latency predictable
Fails in ways you can reproduce
Agent
Path chosen at runtime by the model
Same input, possibly different route
Cost and latency open-ended
Fails in ways you may not reproduce
The answer is often "don't build one"
The part the market has an incentive to leave out
Anthropic's own guidance is to find the simplest solution possible and only add complexity when it's needed — which may mean not building an agentic system at all. Agentic systems trade latency and cost for task performance, and for many applications, optimising a single model call with retrieval and good examples is enough.
That is a strong claim coming from the company that sells the models. It's also the single most useful line to have in your pocket when a client's team is proposing an agent for something a scheduled script would do more cheaply and more reliably.
That is a strong claim coming from the company that sells the models. It's also the single most useful line to have in your pocket when a client's team is proposing an agent for something a scheduled script would do more cheaply and more reliably.
The diagnostic: if you can write down the steps in advance, you have a workflow, and building an agent instead buys you unpredictability you'll pay for in debugging. Reach for panel three only when you genuinely cannot predict how many steps the task takes.
For a non-technical audience
A workflow is a checklist handed to a capable assistant: do this, then this, then this. An agent is a brief: here's the goal, here's what you have access to, tell me when it's done. Every leader already knows which of those two you give someone, and that it depends less on how clever they are than on how well you can specify the outcome and how much damage a wrong turn does.
Sources for this section
Erik Schluntz & Barry Zhang, Building effective agents, Anthropic Engineering, 19 December 2024 — the workflow/agent distinction, the "simplest solution possible" guidance, and the observation that successful implementations use simple composable patterns rather than frameworks. This is a practitioner post from a vendor, not peer-reviewed work; it is credible on how these systems are built in production and should be read as interested on the question of whether to build them at all.
Before there is an agent, there is an augmented model. A model on its own predicts text. Bolt three things to it — the ability to look something up, to act, and to carry state forward — and you have the block every agentic system is built from. Nothing here loops yet.
Figure 2
The augmented model
Anthropic's foundational building block. Note the direction of the arrows: the model reaches for these, rather than being handed them.
Walking someone through this
1
Start with what the model is. A system that predicts likely continuations of text. That's the whole mechanism, and it's worth saying plainly because most of the mystique dissolves here.
2
Then the three attachments. The interesting property is not that they exist — search engines and databases are old — but that the model generates its own queries and chooses its own tools. You supply the capability; it supplies the judgement about when to use it.
3
Close by noting what's missing. No loop, no goal, no stopping condition. Add those three and this becomes an agent — which is the next section, and the whole of the difference.
On the "harness" metaphor
Useful for teaching, weak as an explanation
A common framing in course material is that the model is like an early human with a spear — intelligent but helpless without the house, the fire, and the tools built around it. The metaphor lands well with a non-technical audience and it points at something real: the model is a small part of what people call an agent.
Use it, but know its limit. It implies the surrounding infrastructure is inert scaffolding, when in practice the design of that infrastructure is where nearly all the engineering judgement lives — which tools exist, how they're described, what the model is allowed to touch. The scaffolding isn't the house around the intelligence. It's most of the system.
Use it, but know its limit. It implies the surrounding infrastructure is inert scaffolding, when in practice the design of that infrastructure is where nearly all the engineering judgement lives — which tools exist, how they're described, what the model is allowed to touch. The scaffolding isn't the house around the intelligence. It's most of the system.
Attribution: the spear-and-hearth framing comes from Nick Saraev's agents course, not from research. It's a pedagogical device. Flag it as one when you use it — particularly with an audience who will repeat it.
Sources for this section
Schluntz & Zhang, Building effective agents, Anthropic Engineering, December 2024 — for the augmented LLM as the foundational building block, and for the observation that current models actively use these capabilities, generating their own search queries and selecting appropriate tools.
Add a loop and a stopping condition to the augmented model and you have an agent. Observe what's in front of you, decide what to do, do it, look at what happened, go again. The loop is trivial. What makes it work or fail is the condition that ends it.
Figure 3
The loop
Three steps and a return. Every agent you will ever meet is a variation on this.
Walking someone through this
1
Trace the three boxes left to right. Nothing surprising: look, decide, do. This is how anyone works through a task.
2
Then the return arrow, which is the whole thing. What the action produced — the file it read, the error it hit, the passages it found — is now part of what it observes next time. The agent is reasoning about a world it has already changed.
3
Finally the diamond. Ask who wrote it. The model checks the condition; a person defined it. Vague conditions are the most common reason agents disappoint — the system did loop, it just never knew what finished looked like.
Figure 4
What the loop costs
Context on each pass. Nothing leaves; every observation, every tool result, every thought accumulates.
Two consequences worth carrying. Cost grows faster than the work does, which is why an agent that wanders is expensive rather than merely slow. And the context window is finite, so a long-running session eventually degrades — the practical discipline is short sessions with clear tasks rather than one session left open all day.
Definition of done
The most under-specified part of most agent prompts
The loop ends when the agent judges the goal met. That judgement is only as good as the criteria you gave it. "Research this topic" has no end state; "compile at least ten sources with publication dates, then return a structured summary" does.
Anthropic's guidance is that a task usually terminates on completion, but it's common to add a hard stopping condition as well — a maximum number of iterations — to keep control. Both matter, and they do different jobs: the criteria tell it what success is; the iteration cap protects you when it can't get there.
Anthropic's guidance is that a task usually terminates on completion, but it's common to add a hard stopping condition as well — a maximum number of iterations — to keep control. Both matter, and they do different jobs: the criteria tell it what success is; the iteration cap protects you when it can't get there.
For a non-technical audience
Anyone who has delegated badly recognises this. The failure is rarely that the person couldn't do the work — it's that "look into it and come back to me" contained no description of what coming back successfully looks like. Agents make the cost of vague delegation immediate and itemised.
Sources for this section
Schluntz & Zhang, Anthropic, December 2024 — for agents obtaining ground truth from the environment at each step, and for stopping conditions such as a maximum number of iterations. The observe / think / act naming is Saraev's teaching vocabulary; the same cycle appears in the research literature as the thought–action–observation loop of ReAct (Yao et al., 2022).
The model never runs anything. It emits a structured request saying which function it would like called and with what arguments. Your code decides whether to run it, runs it, and hands back the result. Every claim about what an agent "did" resolves to this exchange.
Figure 5
One tool call, end to end
Seven steps. Watch which column each one happens in — control alternates, and it starts and ends with you.
Walking someone through this
1
Point at step 5 first, then step 4. The model's entire contribution to "sending an email" is step 4 — a piece of JSON naming a function. A person's code sends the email. This is the single most consequential thing to understand about agent risk.
2
Note where a checkpoint goes. Between 4 and 5, and nowhere else. That gap is the only place a human can intervene before an action becomes real — which is why permission design is a coding decision, not a policy one.
3
Then step 1. The tool's name and description are all the model ever knows about it. If the description is vague, the model will use it wrongly, and no amount of prompt instruction fixes a badly described tool.
A tool definition is just a description
There is less here than people expect
A tool is three things: a name, a description in plain English, and a schema saying what arguments it takes. That's the entire interface. The model reads the description and decides, in the same way it decides anything, whether this is the function the situation calls for.
One tool, as the model sees it
{
"name": "search_entries",
"description": "Search journal entries for passages
relevant to a question",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string"}
},
"required": ["query"]
}
}
# That is the whole thing. The description is the
# part that determines whether it gets used well.
Reading test for Phase 3: given a tool definition you didn't write, you should be able to say what the agent can do with it, what it can't, and what would happen if the model passed a badly-formed argument. If you can't answer the third, you can't yet evaluate the tool.
Sources for this section
Anthropic tool-use documentation and Schluntz & Zhang, December 2024 — for the tool-call sequence and the point that a good tool definition includes example usage, edge cases, input format requirements, and clear boundaries from other tools. The seven-step breakdown is a teaching decomposition; the API itself makes no such division.
An agent on its own can do nothing. It produces text saying which tool it would like to run. Everything that makes it useful — files, databases, email, your podcast archive — sits outside the model and is reached through tools you wrote. This section is the map of what's plugged into what.
Figure 6
What the agent is plugged into
Four bands, read top to bottom. The model is in the first one only. Everything below it is ordinary software you or someone else wrote.
Walking someone through this
1
Band one is the only part that thinks. And it never executes anything — it emits a request. Say this out loud; it's the thing people find hardest to believe about AI systems.
2
Band two is the menu. Four functions, each with a name and a description. The agent can only ever do what's on this list. Widen the menu and you widen both the capability and the blast radius — send_email is on a different risk footing from read_file.
3
Band three is optional and people over-weight it. MCP is a plug standard, not a capability. It matters when you want tools someone else maintains. Tools you write yourself skip it entirely.
4
Band four is where your business actually is. The archive, the documents, the client systems. Note that nothing here is AI. It's a database, a folder, and some APIs — which is why "we're adding AI" usually means "we're adding a fourth band we didn't have."
RAG is a tool, not an architecture
The correction most people need
Retrieval-augmented generation is usually described as though it were a kind of system. It's better understood as a way of getting the right text into the prompt, and it shows up in two quite different places.
In a workflow, retrieval is a fixed first step: always search, always paste the results in, then generate. The model never chooses. In an agent, retrieval is one tool among several — the model decides whether this question needs the archive at all, what to search for, and whether the results were good enough to answer or worth searching again. Same components, different location of control. It is the panel-two / panel-three distinction from section 1, applied to retrieval.
In a workflow, retrieval is a fixed first step: always search, always paste the results in, then generate. The model never chooses. In an agent, retrieval is one tool among several — the model decides whether this question needs the archive at all, what to search for, and whether the results were good enough to answer or worth searching again. Same components, different location of control. It is the panel-two / panel-three distinction from section 1, applied to retrieval.
Figure 7
What happens inside one tool call
Opening up search_transcripts. This is all RAG is — four ordinary steps, none of which involve the model.
Where this quietly fails: if step three returns the wrong passages, step four still returns confident, well-written text. Retrieval degrades silently. Nothing in the loop notices, and neither will you unless you build something that checks — which is why retrieval evaluation is the part of this stack worth your attention rather than the part that's becoming a commodity.
Repository, database, MCP — what each actually is
Three words that get used as though they were the same layer
Repository. A folder of files with its version history. For a coding agent like Claude Code, the repository is the environment — it reads, edits and commits inside it, and git is what lets you undo a bad run. For your journal agent, the repository holds the code and the git history; the journal entries themselves live in the database.
Database. Where state lives between runs. A vector database like pgvector is a normal Postgres database with an extra column type that supports "find me the nearest passages" queries. Nothing about it is intelligent.
MCP. An open protocol Anthropic published in late 2024 for connecting models to external tools and data. It standardises how a tool announces itself, so that a tool built by one team works in any host that speaks the protocol. Treat it as a build-time convenience — it is not a runtime component of your agent, and a working agent needs none of it.
Database. Where state lives between runs. A vector database like pgvector is a normal Postgres database with an extra column type that supports "find me the nearest passages" queries. Nothing about it is intelligent.
MCP. An open protocol Anthropic published in late 2024 for connecting models to external tools and data. It standardises how a tool announces itself, so that a tool built by one team works in any host that speaks the protocol. Treat it as a build-time convenience — it is not a runtime component of your agent, and a working agent needs none of it.
For a non-technical audience
The model is a new colleague with no login credentials. Tools are the accounts you issue. MCP is the single sign-on standard that means you don't have to write a new integration for every system. The database and the file store are what were always there. The interesting governance question was never about the colleague's intelligence — it's about which accounts you issued and what a mistake in each one costs.
Standing on
Model Context Protocol, Anthropic, November 2024 — for what MCP standardises. The claim that MCP is a build-time convenience rather than a runtime component is a design judgement, not a documented finding; it follows from the fact that tool definitions can be passed directly in an API call, which you'll see for yourself in section 6.
Everything in the last five sections is about forty lines of Python. Read it slowly. You are not being asked to write this — you are being asked to recognise it, because every agent framework you meet later is this loop with abstraction on top.
A complete agent
One tool, one loop, one stopping condition
This is your journal agent reduced to its skeleton. The retrieval function is left as a call to code written elsewhere — that part is section 5's figure 7. Everything that makes this an agent rather than a script is visible here.
agent.py
import anthropic client = anthropic.Anthropic() # 1 · what the model is allowed to do TOOLS = [{ "name": "search_entries", "description": "Search journal entries for passages " "relevant to a question", "input_schema": { "type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"], }, }] # 2 · the function the model can ask for, but never runs def search_entries(query): return find_nearest_chunks(query, limit=5) messages = [{"role": "user", "content": "What was I avoiding in March?"}] # 3 · the loop, with a hard cap so it cannot run forever for step in range(10): reply = client.messages.create( model="claude-sonnet-4-6", max_tokens=1024, tools=TOOLS, messages=messages, ) messages.append({"role": "assistant", "content": reply.content}) # 4 · definition of done: it stopped asking for tools if reply.stop_reason != "tool_use": print(reply.content[0].text) break # 5 · your code executes; the model only asked results = [] for block in reply.content: if block.type == "tool_use": output = search_entries(**block.input) results.append({ "type": "tool_result", "tool_use_id": block.id, "content": output, }) messages.append({"role": "user", "content": results})
Reading it line by line
1
messages is the context. It only ever grows — every reply and every tool result is appended. That list is figure 4's widening bar, made concrete.
2
for step in range(10) is the loop and the safety cap. Ten passes maximum, whatever happens. Remove that number and a confused agent bills you until you notice.
3
reply.stop_reason != "tool_use" is the definition of done. The model stopped asking for tools, so it believes it can answer. Note how weak that test is — it checks the model's own judgement, which is exactly the unverified loop from section 9.
4
output = search_entries(**block.input) is the moment of execution. Everything before it was text. This line is where an agent touches the world, and it is the line you put a permission check in front of when the tool does something irreversible.
5
The results go back in as a user message. The model has no memory of the call it just made — it only knows what's in messages. Memory, in section 8, is entirely about what you choose to put in this list.
What is not here: no framework, no MCP, no orchestration layer, no vector database. Those are all real and all optional. This is a working agent, and the shape of it should now be recognisable inside anything more elaborate you are shown.
Why start without a framework
A view from the people selling the model
Anthropic's own recommendation is to start with the API directly, because frameworks add abstraction layers that obscure the underlying prompts and responses and make debugging harder — and because incorrect assumptions about what sits under the hood are a common source of error. Their observation across dozens of teams was that the most successful implementations used simple composable patterns rather than complex frameworks.
For your purposes this is doubly true. The evaluation threshold you're building requires seeing the loop. A framework that hides it saves time you don't yet want to save.
For your purposes this is doubly true. The evaluation threshold you're building requires seeing the loop. A framework that hides it saves time you don't yet want to save.
Sources for this section
Schluntz & Zhang, Anthropic, December 2024 — for the framework guidance and the finding on simple composable patterns. The code is written to Anthropic's documented messages API; treat it as illustrative of shape rather than as a tested script, and check parameter names against current documentation before running anything.
Two vocabularies describe the same territory, and people mix them without noticing. Practitioners name patterns by what they do in production. Researchers name them after the paper that introduced them. Knowing both, and knowing which is which, is most of what "being fluent" means in a room where these come up.
Figure 8
Anthropic's five workflow patterns
All five are workflows, not agents — the path is fixed in code. They cover the majority of systems worth building.
Prompt chaining. Split a task into fixed sub-tasks. Trades speed for accuracy.
Routing. Classify first, then send to a handler built for that case.
Parallelisation. Split into independent pieces, or run the same job several times and compare.
Orchestrator-workers. Like parallelisation, but the lead decides what the sub-tasks are. Used for coding across many files.
Evaluator-optimiser. One generates, another critiques, repeat. Only works when the criteria are real.
Walking someone through this
1
Say the punchline first: none of these is an agent. In all five, a developer decided the shape. They're on this page because they're what most real systems turn out to be once you look inside.
2
Contrast the third and fourth. They look identical. The difference is whether the sub-tasks were written in advance or decided at runtime by the lead — which is the workflow/agent line again, drawn inside a single pattern.
3
Linger on the fifth. Evaluator-optimiser only helps when the evaluator has something real to judge against. Two models agreeing with each other is not verification — it's the right-hand panel of figure 10 with an extra step.
The research lineage, and where it overlaps
Different names, adjacent ideas, not a clean mapping
ReAct (Yao et al., arXiv October 2022; ICLR 2023) is the paper usually credited with founding this whole area. Its contribution was interleaving reasoning traces and actions rather than treating them as separate problems — reasoning helps the model track and update its plan, while actions let it gather information from outside itself. The observe/think/act loop in section 3 is ReAct under a teaching name.
Reflexion (Shinn et al., 2023) adds self-evaluation after a task, feeding that critique back into a retry. Plan-and-Execute separates planning from carrying out. Both appear in practitioner material as "agent architectures" alongside Anthropic's patterns, which is where the confusion starts.
The honest position: these are not two competing taxonomies but two different cuts of the same space. Anthropic's evaluator-optimiser and the literature's critic/generator are the same idea named twice. Reflexion is close to evaluator-optimiser with the critic being the same model. Where they genuinely differ is purpose — the papers are demonstrating that a technique improves benchmark scores; Anthropic's patterns are describing what teams ended up shipping.
Reflexion (Shinn et al., 2023) adds self-evaluation after a task, feeding that critique back into a retry. Plan-and-Execute separates planning from carrying out. Both appear in practitioner material as "agent architectures" alongside Anthropic's patterns, which is where the confusion starts.
The honest position: these are not two competing taxonomies but two different cuts of the same space. Anthropic's evaluator-optimiser and the literature's critic/generator are the same idea named twice. Reflexion is close to evaluator-optimiser with the critic being the same model. Where they genuinely differ is purpose — the papers are demonstrating that a technique improves benchmark scores; Anthropic's patterns are describing what teams ended up shipping.
Practical use of this: when someone describes their system with a paper name, ask what the production shape is. When someone describes it with a pattern name, ask what evidence there is that it helps. The two vocabularies hide different things.
Sources for this section
Schluntz & Zhang, Anthropic, December 2024 — for the five patterns and their stated use cases. Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models, arXiv:2210.03629, October 2022, presented at ICLR 2023 — for the reasoning/acting interleave. Shinn et al., Reflexion, 2023. The claim that the two vocabularies are cuts of one space rather than rival taxonomies is my reading, not a position either source states.
Models have no memory. Every call starts from nothing; the only reason a conversation appears continuous is that the whole transcript is resent each time. Memory in an agent is not a model capability — it is a set of decisions you make about what goes back into that list.
Figure 9
Five kinds of memory, by how long they last
Read left to right as lifetime. Only the first is free; everything past it is a system you build or buy.
Walking someone through this
1
Start with the surprise. The model remembers nothing between calls. Ask people what they assumed — most assume something persistent, and the assumption shapes what they think the risks are.
2
Then the first bar. Continuity inside one conversation is just the transcript being resent. It's free, it's finite, and when it runs out the system doesn't tell you — it quietly starts losing the beginning.
3
Everything below is architecture. A database, a retrieval step, a decision about what's worth keeping. Which makes memory a design and governance question — what does this system retain about a client, and who decided?
Where each one actually lives
Concretely, for something the size of your journal agent
In-context is the messages list from section 6. Nothing to build.
Working memory is usually a scratch file the agent writes to mid-task, so a long job survives a restart. Claude Code's memory file is this.
Episodic means summarising a finished session and storing the summary — then retrieving it later, which is the same retrieval machinery as figure 7. Your journal corpus is episodic memory whether or not you call it that.
Semantic is extracted facts held as structured records: you work in Copenhagen, you write in Danish and English. Cheap to store, easy to get wrong, and the category with the sharpest privacy questions.
Procedural is conventions and workflows — in practice, a CLAUDE.md file. It's memory in the sense that it persists, but you write it rather than the system.
Working memory is usually a scratch file the agent writes to mid-task, so a long job survives a restart. Claude Code's memory file is this.
Episodic means summarising a finished session and storing the summary — then retrieving it later, which is the same retrieval machinery as figure 7. Your journal corpus is episodic memory whether or not you call it that.
Semantic is extracted facts held as structured records: you work in Copenhagen, you write in Danish and English. Cheap to store, easy to get wrong, and the category with the sharpest privacy questions.
Procedural is conventions and workflows — in practice, a CLAUDE.md file. It's memory in the sense that it persists, but you write it rather than the system.
Sequencing for your build: in-context and procedural cost nothing and should be right from day one. Episodic is the journal agent's actual subject matter. Semantic extraction is the one to postpone — it's where systems most often confidently store something false about a person and then act on it for months.
Sources for this section
The five-way taxonomy is standard in practitioner writing on agent memory rather than traceable to a single originating paper; the episodic/semantic/procedural distinction is borrowed from cognitive psychology, where it describes human memory and carries empirical baggage that does not transfer. Treat the borrowing as a naming convenience, not a claim that these systems work like minds.
Agents don't succeed because the model is clever. They succeed when the environment tells them the truth. The single best predictor of whether an agentic system will work is whether each step produces a signal the agent can check itself against. Everything else on this page follows from that.
Figure 10
The loop that works, and the loop that only runs
Structurally identical. The difference is what closes the loop — a fact from the world, or the model's own opinion of its work.
Why coding was the first thing agents got good at. Not because code is easy — because code is checkable.
Most advisory work looks like this. It doesn't mean don't use an agent — it means you are the test suite, and the loop has to run through you.
Walking someone through this
1
Cover the middle boxes and ask which is which. You can't tell. The two systems are the same shape, the same cost, the same impressive-looking session log.
2
Then reveal them. On the left, something outside the agent decides whether it succeeded. On the right, the agent grades its own homework — and it grades generously, because fluency is what it optimises for.
3
The question to leave them with: for the task you're proposing to automate, what plays the role of the test suite? If the honest answer is "nothing", you haven't found a bad use case — you've found one where a human has to stay inside the loop.
Three systems, traced through the bands
Same architecture, very different odds of working
Take the four bands from section 5 and fill them in for three real systems. What separates them isn't sophistication — it's the third row.
Coding agent on a repo
Environment: the repository, git, a test suite
Tools: read, edit, run shell
Ground truth: tests pass or they don't
Stops when: the suite goes green
Undo: git revert
Customer support agent
Environment: order database, knowledge base, ticketing
Tools: look up order, issue refund, close ticket
Ground truth: the customer confirms it's resolved
Stops when: ticket closed or escalated
Undo: partial — a refund is real money
Your journal agent
Environment: pgvector store of your entries
Tools: search entries, read one, summarise
Ground truth: none — you are the only check
Stops when: it produces an answer
Undo: not needed — it only reads
Read the third row across. The coding agent gets a hard signal, the support agent a soft one, yours none at all. That's not a flaw in your design — it's why the journal agent is a rehearsal rather than a product, and why its blast radius being zero (read-only) is the thing that makes it safe to build first.
Fix the tool, not the prompt
The most transferable practical lesson in the literature
Building their SWE-bench agent, Anthropic report spending more time optimising the tools than the overall prompt. One concrete case: the model kept making mistakes with relative filepaths once the agent had moved out of the root directory. Rather than adding a prompt instruction telling it to be careful, they changed the tool to require absolute paths — and the model then used it without error.
The generalisation is worth carrying into any system you build or review: when an agent repeatedly makes the same mistake, that's usually a design flaw in the tool, not a reasoning failure in the model. Anthropic's own frame is that as much effort should go into the agent-computer interface as teams already put into human-computer interfaces — a good tool definition includes example usage, edge cases, input format requirements, and clear boundaries against the other tools.
The generalisation is worth carrying into any system you build or review: when an agent repeatedly makes the same mistake, that's usually a design flaw in the tool, not a reasoning failure in the model. Anthropic's own frame is that as much effort should go into the agent-computer interface as teams already put into human-computer interfaces — a good tool definition includes example usage, edge cases, input format requirements, and clear boundaries against the other tools.
Why this lands with an executive audience
It's the same move as redesigning a form so people stop filling it in wrong, rather than sending another email asking them to be careful. Recurring human error is usually a systems problem; the finding here is that the same is true of agents, and that the fix is in the interface rather than the instruction.
The other three conditions
Cheap to get right, expensive to skip
An explicit definition of done. The task normally ends when the agent judges it complete, which is why it's common to add a hard stopping condition as well — a maximum number of iterations. Without one, an agent that can't succeed will keep spending your money trying.
Checkpoints before irreversible actions. Anthropic's guidance is to build points where the agent pauses for human review, especially before anything that can't be undone — approving payments, deleting data, sending on your behalf. Note this is a design decision made when you write the tools, not something you can bolt on afterwards.
A narrow menu. Every tool you add widens both what the agent can do and what it can do wrong. The support agent above is a useful example: look_up_order is harmless, issue_refund moves money. Those two belong on different sides of a human checkpoint even though they sit in the same tool list.
Checkpoints before irreversible actions. Anthropic's guidance is to build points where the agent pauses for human review, especially before anything that can't be undone — approving payments, deleting data, sending on your behalf. Note this is a design decision made when you write the tools, not something you can bolt on afterwards.
A narrow menu. Every tool you add widens both what the agent can do and what it can do wrong. The support agent above is a useful example: look_up_order is harmless, issue_refund moves money. Those two belong on different sides of a human checkpoint even though they sit in the same tool list.
Sources for this section
Schluntz & Zhang, Building effective agents, Anthropic Engineering, December 2024 — for ground truth from the environment, stopping conditions, human checkpoints before irreversible actions, and the SWE-bench filepath example. The claim that verifiability predicts whether an agentic system works is my inference from their material rather than a stated finding of theirs, though it's consistent with why their two named success domains — coding and customer support — are both ones with clear success criteria and feedback loops. Treat it as a strong working hypothesis, not a result.
Agents fail in a specific way: quietly, and more often the longer they run. Not because any single step is unreliable, but because a long chain of reliable steps is not itself reliable. This is arithmetic, not pessimism.
Figure 11
Why long chains fail
Probability that every step succeeds, assuming each one is right 95% of the time. Illustrative arithmetic, not a measurement.
Walking someone through this
1
Ask for a guess before showing the third bar. Almost everyone overestimates. The intuition that 95% is "nearly always" survives a single step and collapses over ten.
2
Then apply it to the demo they were shown. A demo is one run that worked. This chart is the distribution the demo was drawn from, and the vendor chose which run to record.
3
The design implication, not the despair. Shorten the chain, verify at each step so errors are caught rather than compounded, or keep a human at the point where it matters. All three are ways of refusing to multiply.
Blast radius
The question that should determine how much autonomy you grant
Reliability tells you how often something goes wrong. Blast radius tells you what it costs when it does, and it's the more useful number because you control it directly through which tools you expose.
A read-only agent has a blast radius of nothing: worst case, it says something wrong and you notice. An agent that writes to files has git as an undo. An agent that sends email or moves money has no undo at all — the action is real the instant your code executes it, at line 5 of section 4's diagram.
A read-only agent has a blast radius of nothing: worst case, it says something wrong and you notice. An agent that writes to files has git as an undo. An agent that sends email or moves money has no undo at all — the action is real the instant your code executes it, at line 5 of section 4's diagram.
Reversible
reads, searches, drafts
no checkpoint needed
run it unattended
Recoverable
edits files, commits code
git is the safety net
review before merge
Irreversible
sends, pays, deletes, publishes
human checkpoint, always
never unattended
Anthropic's guidance is explicit here: build checkpoints where agents pause for human review, particularly before irreversible actions such as approving financial transactions or deleting data. Note that this is a decision made in your tool code, not a setting — an agent cannot be made safe after the fact by asking it nicely.
The gap between a demo and a system
What to ask when you're shown one
Agents demo extraordinarily well, because a successful run is genuinely impressive and a failed run is simply not recorded. The useful questions when a client's team presents one are not about the model.
What plays the role of the test suite? If nothing verifies the output, the impressive session log is evidence of fluency, not accuracy. What happens on the bad run? Not whether it fails, but what state the world is in afterwards. How many steps? Then look at figure 11. What's on the tool list? That is the actual scope of what this system can do to you, and it's usually shorter and more alarming than the narrative around it.
What plays the role of the test suite? If nothing verifies the output, the impressive session log is evidence of fluency, not accuracy. What happens on the bad run? Not whether it fails, but what state the world is in afterwards. How many steps? Then look at figure 11. What's on the tool list? That is the actual scope of what this system can do to you, and it's usually shorter and more alarming than the narrative around it.
For a non-technical audience
The relevant precedent is not previous software. It's hiring someone very fast, very confident, and very new, then deciding which systems to give them access to on day one. Nobody would answer "all of them", and yet that is what a permissive tool list amounts to.
Sources for this section
Schluntz & Zhang, Anthropic, December 2024 — for compounding errors as a named risk of agent autonomy, the recommendation of sandboxed testing with guardrails, and human checkpoints before irreversible actions. The 95% arithmetic is illustrative: it assumes independent steps, which real agents are not, and a uniform per-step success rate, which no system has. It is a way of showing the shape of the problem, not a measurement of any product.
Everything in this primer, applied to one small system you are actually going to build. The journal agent is deliberately modest: read-only, one tool, a corpus of your own writing. It is the rehearsal for the podcast archive, and the reason to build it first is not that it is easier but that getting it wrong costs nothing.
Figure 12
The journal agent, whole
One question, traced through every layer in this primer.
Walking someone through this
1
Name each band as you pass it. The loop is section 3. The tool call is section 4. The vector store is section 5. The retrieval inside it is figure 7. Nothing new has been introduced — this is the primer folded into one page.
2
Point at what is not here. No MCP, no framework, no memory system, no orchestration, no sub-agents. A useful working agent, built from the smallest possible set of parts.
3
Then the honest part. Nothing in this diagram checks whether the passages were the right ones. If retrieval returns the wrong March, the answer is still fluent and still confident. You are the verification step, and that is a design fact rather than an oversight.
Why this one first
And what changes at podcast scale
The journal agent and the podcast agent are architecturally identical. What differs is scale and stakes, and both differences bear on retrieval rather than on the agent.
At journal size, you know the corpus. If it returns the wrong entry you will notice immediately, because you wrote it. That is why this is the right rehearsal: you can evaluate the retrieval by inspection, which is exactly the skill that stops being available later. Across two thousand interviews you will not know what it failed to find, and no error will surface — the answer will simply be shallower than it should have been, in a way that reads as fine.
This is the point about commoditisation, made concrete. Embeddings, vector storage and retrieval are all becoming things you buy rather than build. That doesn't reduce what you need to understand; it relocates the failure to a place that is harder to see. Build the small one while the failures are still visible to you.
At journal size, you know the corpus. If it returns the wrong entry you will notice immediately, because you wrote it. That is why this is the right rehearsal: you can evaluate the retrieval by inspection, which is exactly the skill that stops being available later. Across two thousand interviews you will not know what it failed to find, and no error will surface — the answer will simply be shallower than it should have been, in a way that reads as fine.
This is the point about commoditisation, made concrete. Embeddings, vector storage and retrieval are all becoming things you buy rather than build. That doesn't reduce what you need to understand; it relocates the failure to a place that is harder to see. Build the small one while the failures are still visible to you.
Journal agent · Phase 5
Corpus you wrote and remember
Bad retrieval is obvious
Read-only — blast radius zero
Purpose: learning to see
Podcast agent · after
~2,000 interviews you cannot hold
Bad retrieval is invisible
Still read-only — keep it that way
Purpose: actual advisory leverage
The one thing to build that isn't in the diagram: a small set of questions you already know the answer to, run against the system whenever you change the chunking or the embedding model. That is your test suite. Without it, the podcast agent is figure 10's right-hand panel at scale.
What you should now be able to do
The evaluation threshold, stated concretely
Shown an agentic system you did not build, you should be able to establish: whether it is a workflow or an agent, by asking who fixed the order of operations. What is on its tool list, and which of those tools are irreversible. What ends the loop, and whether that condition is real or the model's own opinion. What verifies the output, and if the answer is nothing, who is expected to catch the errors. How long the chain is, and therefore what figure 11 says about it.
None of those questions requires you to write the system. All of them require you to have read one, which is what section 6 was for.
None of those questions requires you to write the system. All of them require you to have read one, which is what section 6 was for.
A closing note on sources
This primer leans on one practitioner post from Anthropic, two research papers, and a body of course material that is useful on mechanics and interested on the question of whether to build. Where a claim is my inference rather than a documented finding, it has been marked as such in the section it appears in. The area moves quickly and this reflects it as of mid-2026; the loop, the tool call and the compounding-error arithmetic are the parts least likely to date.