Build the agents that last.

Workflows vs agents.

The clearest framing: “Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage.”

The line matters because almost every “agent” failure in industry is actually a workflow that was prematurely promoted. If you can write down the steps in advance, build a workflow. Reach for an agent only when the steps cannot be predicted — the model has to decide.

The five workflow patterns.

Five composable building blocks. Memorize them; almost every production system is a combination of these.

The orchestrator-workers pattern.

The pattern most people reach for, often wrong. The orchestrator decides the sub-tasks on every input. Workers execute. The orchestrator synthesizes.

Coding agents are the canonical example: when fixing a complex bug across multiple files, the orchestrator reads the symptom, decides which files to touch, dispatches a worker per file, then synthesizes the diff. The sub-tasks aren’t predefined — they emerge from reading the symptom.

Why this is harder than it looks

• The orchestrator has to be good at decomposition, not just retrieval. Few-shot examples of good plans are gold.
• Workers each need their own context. The orchestrator’s prompt should give each worker only what that worker needs.
• Synthesis is its own skill. Combining N worker outputs into one coherent response is where teams under-invest.

Distinguish from parallelization

Parallelization runs pre-defined sub-tasks. Orchestrator-workers generates the sub-tasks per input. The first is a static fan-out. The second is a dynamic delegation. Different cost, different complexity, different debugging story.

The orchestrator prompt template

The prompt structure that consistently produces well-shaped sub-task lists instead of "let me think about this":

Copy# Drop in as the orchestrator's system prompt
You are the orchestrator. You do not solve the user's problem directly —
you decide how to decompose it and dispatch workers.

For this input: [user's request]

Step 1 — Decompose
List 2-5 sub-tasks, each scoped narrowly enough that one specialized
worker can handle it alone. Each sub-task should be:
- Independently completable (no cross-worker dependency)
- One sentence describing the worker's job
- One sentence describing what "done" looks like

Step 2 — Dispatch
For each sub-task, draft the exact prompt you would send to a worker.
The worker has no context other than this prompt.

Step 3 — Synthesis plan
Describe how you'll merge the workers' outputs into a single answer.
State the merge rule BEFORE you see the outputs:
- Union (combine everything)
- Vote (majority wins)
- Prioritize (worker N's output takes precedence)
- Reduce (extract a single field from each)

DO NOT produce the user's answer in this step. Only the plan and
the worker prompts.

Wait for me to approve before dispatching.

Why the “wait to approve” step matters: Most orchestrator failures aren’t bad workers — they’re bad decomposition. Forcing the orchestrator to expose its sub-task list before dispatching saves you from running 5 workers on the wrong 5 questions.

The simplicity-first principle.

The principle that prevents most "agent" disasters: “Find the simplest solution possible, and only increase complexity when needed.”

Walk up the ladder, never the lift:

The line you will save your team: “Workflows offer predictability and consistency for well-defined tasks, whereas agents are the better option when flexibility and model-driven decision-making are needed at scale.”

Context as a finite resource.

The framing: “Find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome.”

Three problems that scale together as agents run longer:

1. The context window fills up. Requests start getting rejected.
2. Token costs scale with context size. Every additional turn pays the cumulative price.
3. Model performance degrades as context grows. Empirically measured. Not a small effect.

Long-running agents need explicit strategies for keeping the context lean. Three of them are the rest of this day.

The cheapest win once your stable prefix is identified is prompt caching. Rather than re-teach the mechanics here, do the runnable drill in Practice 04 · “make the cache fire” — it walks the cache_control placement and has you watch cache_read_input_tokens jump on the second call. This unit’s lab below uses that same usage field as its verify.

Compaction.

Summarize the conversation history when approaching context limits. Distil critical information; discard the redundant. The advice that pays off: “Maximize recall to ensure your compaction prompt captures every relevant piece of information from the trace.”

The implementation

• Trigger. When context utilization crosses a threshold (e.g. 70%), kick off compaction.
• Prompt. “Summarize the trace so far. Preserve every fact, decision, and open commitment. Drop everything else.”
• Replace. Substitute the new summary message in place of the compacted turns. Continue.
• Hook before, save after. Claude Code’s PreCompact hook lets you persist anything about to be lost.

Structured note-taking.

Instead of keeping everything in context, the agent writes notes to external storage and retrieves them on demand. A NOTES.md file. A wiki. A database.

This is exactly the LLM Wiki pattern (Practice 05) at a more general level. The conversation history grows linearly with turns; the notes file grows logarithmically with new knowledge. The model attends to what it needs, when it needs it.

Sub-agent architectures.

Specialized agents handle focused tasks and return condensed summaries (typically 1,000-2,000 tokens) to a coordinating agent. The main agent doesn’t carry the full detail; only the conclusions.

The key insight: each sub-agent has its own context window. The exploration cost stays inside the sub-agent. The parent only ever sees the synthesized output. This is why Claude Code uses subagent dispatch for parallel investigation — the main session’s context stays clean.

Agent affordances, not API parity.

The biggest mistake in tool design: thin wrappers around your existing API. The correction: “Build tools matching how agents think.”

An example from the post: implement search_contacts instead of list_contacts, because agents have limited context and shouldn’t waste tokens reading irrelevant data.

Consolidate, don’t fragment

Instead of separate list_users, list_events, create_event tools, build a unified schedule_event tool that handles multiple steps internally. The agent thinks in jobs, not endpoints.

Namespacing.

As agents gain access to dozens of MCP servers and hundreds of tools, namespacing is what keeps them selecting the right one.

Copy# Pick a convention and stick with it.

# By service (asana_*, jira_*, slack_*):
asana_search · asana_create_task · asana_get_user
jira_search  · jira_create_issue · jira_get_user

# Or by resource within a service:
asana_projects_search · asana_users_search · asana_tasks_create

Don’t mix conventions across servers. Once you have 50+ tools, namespace consistency is what separates an agent that picks the right tool from one that picks the closest-sounding tool.

Return meaningful context, not raw data.

The principle: “Agents reason better with human-readable fields and simplified outputs than with raw technical IDs.”

Skip the IDs

UUIDs, mime types, internal flags — the model can’t reason about them. Return name, not uuid. Return file_type: "pdf", not mime_type: "application/pdf". Save the technical fields for the next-call inputs.

Offer two response modes

• Concise — high-signal fields only (~72 tokens in a well-tuned tool).
• Detailed — includes IDs for chaining (~206 tokens in their example).

Errors should teach, not just signal failure

We recommend: “Provide constructive feedback rather than opaque codes.” An error message like “Try a more specific search filter” is worth ten of “ERR_TOO_MANY_RESULTS”.

Prototype · Evaluate · Collaborate.

An iterative three-phase process for tool design, in this order.

The result on internal benchmarks: “Testing on internal Slack and Asana tools, Claude-optimized implementations significantly outperformed human-written versions on held-out test sets.”

The implication: paste your tool descriptions into Claude, ask it to make them more agent-friendly, run the new versions through your eval suite, keep the wins. Most of your tool-quality improvements live one prompt away.

One page you keep on your desk.

By the end of this practice, you should be able to look at a new agent task and pick the right pattern in under 5 minutes. This cheatsheet is the working artifact — copy it into a doc, pin it, refer to it on every new build.

Copy## AGENT PATTERN SELECTION — pick the right one in 5 minutes

## STEP 1 — Is this a workflow or an agent?
- Predefined steps, deterministic order? → WORKFLOW (cheaper, more debuggable)
- Steps need to be decided per input, model-driven? → AGENT
- When in doubt: start as workflow. Promote to agent only if
  step-determination is itself the hard problem.

## STEP 2 — Pick the workflow pattern (if workflow)
| Pattern               | Pick when…                                                       |
|-----------------------|------------------------------------------------------------------|
| Prompt chaining       | Output of step N is input to step N+1; clear handoff             |
| Routing               | Input falls into one of K categories; each gets a different path |
| Parallelization       | Sub-tasks are PREDEFINED and independent                         |
| Orchestrator-workers  | Sub-tasks must be DECIDED per input by an LLM                    |
| Evaluator-optimizer   | Quality of output matters more than latency; iterate to improve  |

## STEP 3 — Context budget check (every pattern)
For every new agent, run these 4 checks BEFORE writing prompts:
- [ ] OFFLOAD: what can live outside the context window? (files, DB, search)
- [ ] RETRIEVE: what's loaded only when relevant? (RAG, lookup)
- [ ] ISOLATE: which steps run in fresh sub-agent contexts?
- [ ] REDUCE: what gets compacted/summarized when context fills?

## STEP 4 — Tool design audit
For every tool the agent uses:
- [ ] Match agent affordances, not API parity. (Don't expose 50 raw endpoints;
      expose 5 verbs the agent thinks in.)
- [ ] Return MEANINGFUL fields, not raw IDs.
- [ ] Namespace clearly: `gh.pr.merge`, not `merge`.
- [ ] Errors teach the agent what to do next, not just signal failure.
- [ ] Tool description starts with WHEN to use it, not HOW.

## STEP 5 — Eval & ship
- [ ] One test case per intended use, written before coding.
- [ ] One adversarial test case (input that should fail safely).
- [ ] Cost estimate per typical run (tokens × rate × steps).
- [ ] Decide simplicity-first: if a single prompt to a strong model gets
      80% of the value, ship that first.

## RED FLAGS — stop and reconsider
- Your orchestrator is doing the work itself (not delegating)
- Your workers need to talk to each other (couple them or merge them)
- Your context is over 80% full mid-task (compaction time)
- You picked agent because it "felt" right — workflow probably wins
- You have 7+ tools per agent (consolidate)