Building Effective Agents, Read Closely

What it takes off your plate: turning "agent or not" into a question with an answer

Verbatim (Erik Schluntz / Barry Zhang, 2024-12-19):

Workflows are systems where LLMs and tools are orchestrated
through predefined code paths.

Agents are systems where LLMs dynamically direct their own
processes and tool usage, maintaining control over how they
accomplish tasks.

The line lands on a question you can answer on the spot: who decides which tool gets called next — your code, or the model? Code decides it, and it is a workflow no matter how many layers it wears. The model decides it, and it is an agent even at twenty lines. An elaborate diagram can still be a workflow; a single while-loop can be an agent.

The companion code: those five official notebooks

Reading alone leaves you feeling like you understood it. The reference implementation lives in the official cookbook — note that the repo was renamed from anthropic-cookbook to claude-cookbooks (old links redirect; the directory path is unchanged):

git clone https://github.com/anthropics/claude-cookbooks
cd claude-cookbooks/patterns/agents

basic_workflows.ipynb               # chaining / routing / parallel
evaluator_optimizer.ipynb           # the evaluate-refine loop
orchestrator_workers.ipynb          # orchestrator and workers
async_multi_agent_orchestration.ipynb
latency_multi_agent.ipynb           # multi-agent under latency/budget
util.py  prompts/                   # shared helpers and prompts

Every notebook is a bare implementation with no framework underneath, which is exactly the essay's stance: many patterns can be implemented in a few lines of code. When not to bother: if what you need is production-grade retries, observability and persistence, none of that is here — these are teaching aids, not a foundation. (Per the GitHub repo page, 53.1k stars, 2026-09.)

The first thing you can actually run: the top rung

Only the last of the five patterns needs a real agent loop, and that rung now ships officially:

npm install @anthropic-ai/claude-agent-sdk   # Node 18+
pip install claude-agent-sdk                 # or Python 3.10+
export ANTHROPIC_API_KEY=your-api-key

from claude_agent_sdk import query, ClaudeAgentOptions

async for m in query(
    prompt="Review utils.py for bugs that would crash. Fix them.",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Glob"],
        permission_mode="acceptEdits")):
    print(m)

Lifted from the official quickstart. What it takes off your plate is writing the agent loop yourself: tool calls, context management, retries and the permission gate all live in the library. When not to install it: your task is three fixed steps, each one predictable — by the essay's own criteria that is prompt chaining, so call the API three times and skip dragging in a whole harness. Also note that since v0.1.0 the SDK no longer loads Claude Code's system prompt by default; for the old behavior you pass {"type":"preset","preset":"claude_code"} explicitly.

Mechanism: the five patterns are a ladder, not a menu

The ladder stands on what the essay calls the augmented LLM: an LLM enhanced with augmentations such as retrieval, tools, and memory. All five patterns are built on it; they differ only in who orchestrates it.

The rungs map one-to-one onto claude-cookbooks/patterns/agents/: (1)(2)(3) all live in basic_workflows.ipynb, (4) in orchestrator_workers.ipynb, (5) in evaluator_optimizer.ipynb, and (6) has no notebook of its own — because it is the query() loop inside claude-agent-sdk. The essay gives each rung a fitness test short enough to quote in a design review:

• (1) Chaining — the task can be easily and cleanly decomposed into fixed subtasks. The operative word is fixed: if you can draw the flowchart, use this.
• (2) Routing — distinct categories that are better handled separately. Support triage and easy-vs-hard model selection both live here.
• (3) Parallelization — don't conflate the two variants: sectioning splits into independent subtasks run at once and buys speed; voting runs the same task repeatedly for consensus and buys confidence.
• (4) Orchestrator-workers — complex tasks where you can't predict the subtasks needed. That sentence is the whole border with (3): is the subtask list hardcoded or generated at runtime?
• (5) Evaluator-optimizer — when we have clear evaluation criteria, and when iterative refinement provides measurable value. Without an objective yardstick you get two models complimenting each other.
• (6) Agents — open-ended problems where it's difficult or impossible to predict the required number of steps. The essay states the bill too: higher costs, and the potential for compounding errors.

The essay closes on three principles worth pinning above the desk: simplicity in the design, transparency about the agent's planning steps, and a carefully crafted ACI — tool documentation and testing polished the way you would polish an API reference. The third is the most underrated, and the next section is its manual.

Practice and limits: auditing a 2024 essay against three later posts

1. What multi-agent really costs

Anthropic's How we built our multi-agent research system (2025-06-13) opens the books on rung (6): a multi-agent system with Opus 4 as lead and Sonnet 4 subagents beat single-agent Opus 4 by 90.2% on their internal research eval. The bill: agents burn roughly 4x the tokens of chat, and multi-agent systems about 15x; parallel tool calling cut research time by up to 90% on complex queries. The same post draws the border: domains that need every agent to share one context, or where subtasks depend heavily on each other, are a bad fit — it names most coding tasks involve fewer truly parallelizable tasks than research. When not to reach for it: when the task isn't worth 15x the tokens.

2. Appendix 2, grown up

The essay's second appendix is called "Prompt Engineering your Tools"; Writing effective tools for AI agents (2025-09-11) is what it became, and the only operating manual for the ACI principle: consolidate tools (one schedule_event instead of list_users/list_events/create_event), namespace them (asana_search vs jira_search to mark boundaries), return token-efficient responses (Claude Code caps tool responses at 25,000 tokens by default — do your own pagination, filtering, truncation), return high-signal fields only (name and file_type, not uuid and mime_type), and write the eval before tuning descriptions.

3. The half the 2024 essay barely covers

Effective context engineering for AI agents (2025-09-29) fills the blind spot: context is not free. Four techniques — compaction (summarize history near the limit), structured note-taking (persist progress to external memory such as a NOTES.md), sub-agent architectures (work in a clean window, return only a condensed summary), and just-in-time retrieval (keep lightweight identifiers, load on demand). One governing line: find the smallest possible set of high-signal tokens.

4. The framework list: this is a living document

Open the essay today and "When and how to use frameworks" names the Claude Agent SDK, Strands Agents SDK by AWS, Rivet and Vellum — and the Claude Agent SDK is a rename of claude-code-sdk, a name that did not exist on publication day in 2024-12. Don't mistake old notes for the present state. Two you can install:

pip install strands-harness      # or npm i @strands-agents/harness
pip install -U langgraph

strands-agents/harness-sdk sells end-to-end harness control, "any model, any cloud" (per the GitHub repo page, 8.5k stars, 2026-09); langchain-ai/langgraph is a low-level orchestration framework for stateful agents (per the GitHub repo page, 42.5k stars, 2026-09). When to install neither: the essay says start with the LLM API directly, because frameworks create extra layers of abstraction that can obscure the underlying prompts and responses, making them harder to debug — and when you cannot see the prompt you actually sent, every tuning decision is superstition.

Cost and alternatives: the price of this essay is being used as a map

1. Terminology drift. The cookbook repo was renamed, the SDK was renamed, the framework list changed hands. Every proper noun you copy out of this essay needs re-checking at a primary source; every criterion you copy still holds.
2. It doesn't discuss context. In 2024 the context window wasn't yet the main design constraint. Read only this and go build rung (6), and you hit the wall around tool call thirty.
3. "90.2%" is the easiest number to over-generalize. It came from an internal research-task eval, and the very same post goes on to say coding has far less that is genuinely parallelizable.
4. Its minimalism gets read backwards. "Keep it simple" does not mean "never build an agent"; it means "don't move up a rung before you've measured the gain".

Four rungs below the agent

1. One good prompt. The essay's first recommendation is to optimize the single call, adding retrieval and in-context examples where they help.
2. Three chained calls. Twenty lines: debuggable, breakpointable, cost-predictable.
3. A skill or a CLAUDE.md. If all you want is "do it this way every time", that's Skill 6's territory — no agent loop required.
4. One hook. If all you want is "this must happen every time", that's last issue's territory — no model judgment required.