Anthropic's 'Building Effective Agents', Simplified

Quick answer: Anthropic's "Building Effective Agents" says most good AI systems are simple. Start with one well-prompted model call. Add fixed workflows (chaining, routing, parallel calls, orchestrator-workers, evaluator-optimiser) when a task needs more steps. Use a free-running agent only for open-ended work, and design its tools as carefully as a user interface.

Building Effective Agents is one of the most linked pieces of guidance on agentic AI. It is short, but it packs in a lot of vocabulary. This post retells it in plain English, with an everyday example for each pattern and a table to help you pick one.

One caveat first. Anthropic published the post in December 2024, and the page now notes that much of the tooling landscape has changed since then. The patterns themselves have aged well. Product names have not, so treat the framework list as a snapshot.

This post is part of our AI software development lifecycle series. If you want OpenAI's view of the same topic, read our companion piece on OpenAI's practical guide to building agents.

What is the difference between workflows and agents?

Anthropic uses agentic systems as the umbrella term, then splits it in two:

• Workflows. A large language model (LLM) and its tools follow code paths you wrote in advance. Your code stays in charge.
• Agents. The model directs its own process. It decides which tool to call next and when it has finished.

A useful picture: a workflow is a recipe; an agent is a cook who is told what dinner should be and chooses the steps.

Neither is "better". Anthropic says workflows suit well-defined tasks where you want predictability. Agents suit work that needs flexibility and model-driven decisions. Both usually cost more time and money than a single call, in exchange for better results on harder tasks.

Why does Anthropic say "start simple"?

The headline advice is to find the simplest thing that works and add complexity only when it clearly helps. Often that means no agentic system at all. Anthropic notes that one LLM call, improved with retrieval and a few in-context examples, is frequently enough.

On frameworks, Anthropic is cautious. Libraries can save you from boring plumbing. But extra abstraction layers can hide the actual prompts and responses, which makes bugs harder to find and tempts you into complexity you do not need. Its suggestion is to start with the model's API directly. If you adopt a framework, understand what it does underneath.

The post ends with three principles:

1. Keep the agent's design simple.
2. Make it transparent by showing the agent's planning steps.
3. Craft the agent-computer interface carefully, with good tool documentation and testing.

What is the "augmented LLM"?

Every pattern builds on one block: a model with extras such as retrieval (looking things up), tools (taking actions) and memory (keeping notes). The model can write its own search queries, choose tools and decide what to remember.

Anthropic advises tailoring these extras to your use case and giving the model a clear, well-documented interface to them. It mentions the Model Context Protocol (MCP), an open standard for connecting tools to models, as one way to do that.

What are the agentic workflow patterns?

Here are the five workflow patterns and the autonomous agent, each with a one-line everyday example of our own.

1. Prompt chaining

Break the job into fixed steps, where each call works on the output of the last. You can add a "gate", a simple code check, between steps.

Everyday example: write a recipe card, check it lists every ingredient, then translate it.

Anthropic's own examples: write marketing copy then translate it; draft an outline, check it, then write the document. You trade a little speed for accuracy.

2. Routing

Classify the input first, then send it to a specialised prompt or process.

Everyday example: a school office sorts post into "parents", "suppliers" and "council" trays before anyone reads it.

Anthropic mentions sending refund, technical and general customer questions down different paths, and sending easy questions to a smaller model and hard ones to a more capable one.

3. Parallelisation

Run several calls at once and combine the answers in code. Anthropic describes two flavours:

• Sectioning: split a task into independent parts. One call answers the user while another screens the input for inappropriate content.
• Voting: run the same task several times and compare. Several prompts review the same code for security flaws.

Everyday example: three friends each proofread a different chapter (sectioning), or all three read the same cover letter and you go with the majority view (voting).

4. Orchestrator-workers

A lead model breaks the task down at runtime, hands parts to worker calls, then merges their results. The difference from parallelisation is that nobody knows the subtasks in advance.

Everyday example: a wedding planner who decides on the day which helpers handle flowers, seating or music, depending on what has gone wrong.

Anthropic's examples are coding products that change several files, where the files depend on the request, and searches that pull from many sources.

5. Evaluator-optimiser

One call produces an answer; another critiques it; the first revises. Repeat until it passes.

Everyday example: a writer and an editor passing a draft back and forth.

Anthropic says this works when you have clear criteria and feedback actually improves the result, such as literary translation or multi-round research where the evaluator decides if more searching is needed.

6. Autonomous agents

The agent takes a goal from a person, plans, then works in a loop: call a tool, look at the real result (Anthropic calls it "ground truth" from the environment), decide the next step. It can pause for human input at checkpoints and should have stopping conditions, such as a maximum number of turns.

Everyday example: asking a capable assistant to "sort out the broken boiler", and they phone around, book someone and report back.

Anthropic notes these are often simple to build: a model using tools in a loop. The hard part is trust. Autonomy raises cost and lets errors pile up, so Anthropic recommends extensive testing in a sandbox (an isolated environment) plus guardrails.

Which pattern should you use when?

Pattern	Use it when	Avoid it when
Single call + retrieval	The task fits in one good prompt	It keeps failing despite better prompts
Prompt chaining	Steps are fixed and known in advance	Steps vary per request
Routing	Inputs fall into distinct, classifiable types	Categories blur together
Parallelisation	Parts are independent, or you want several opinions	Each step depends on the last
Orchestrator-workers	Subtasks only become clear at runtime	A fixed chain would do
Evaluator-optimiser	You can state clear pass/fail criteria	"Good" is purely a matter of taste
Autonomous agent	Open-ended work with unpredictable steps, in a safe sandbox	Mistakes are costly and hard to undo

Anthropic stresses these are not rules. Mix and match them, measure the results and only keep complexity that earns its place.

Where does Anthropic say agents work well?

The appendix names two areas:

• Customer support. Conversations need outside data and actions, such as order history or refunds, and success is easy to define.
• Coding agents. Code can be checked with automated tests, the agent can iterate on test failures, and output is measurable. Anthropic adds that human review is still essential so the change fits the wider system.

How should you design tools for an agent?

This is the most practical part of the post. Anthropic calls the tool layer the agent-computer interface (ACI), by analogy with the human-computer interface. Its advice, paraphrased:

1. Pick formats the model finds easy. The same edit could be a diff or a whole-file rewrite. Some formats force the model to count lines or escape strings, which it does badly. Prefer formats that look like text it has seen plenty of online, and give it room to think before committing.
2. Write tools like docs for a new colleague. Include example usage, edge cases, input rules and how the tool differs from similar ones.
3. Rename and rewrite until it is obvious. If two tools look alike, clearer names and descriptions help most.
4. Test with many example inputs and watch where the model slips.
5. Mistake-proof the arguments. Anthropic borrows the Japanese term poka-yoke: shape the tool so the wrong call is hard to make.

The memorable example: while building its SWE-bench coding agent (SWE-bench is a public test set of real GitHub issues), Anthropic says it spent more time on tools than on the main prompt. The model tripped over relative file paths once it had moved out of the root folder. Requiring absolute paths fixed it.

We cover the wider idea of shaping what a model sees in context engineering explained.

What we do at Pocket Grove

In our studio, Cong Le maintains around 53 iOS and Android apps with Claude Code and Codex. This guide matches what we have found, though we are a small team and this is opinion, not a study.

• Most work is a workflow, not a free agent. Per-app TASKS.md files and skills lay out the steps; the agent fills them in.
• Orchestrator-workers only for real parallelism. We spin up subagents when there are several independent tasks, and do small edits in the main session.
• Ground truth beats self-reports. Headless tests are the agent's feedback loop, and we re-check what an agent says it finished.
• Absolute paths everywhere. Our shared instructions ask for them, for the same reason Anthropic gives.
• A human gate before release. No app goes to a store without Cong's explicit approval.

Our shared instruction file is one AGENTS.md with a CLAUDE.md symlink. We explain why in stop putting everything in CLAUDE.md.

Sources

• Building Effective Agents — Anthropic — https://www.anthropic.com/engineering/building-effective-agents