Agent Architecture

Two ways to arrange the same parts

A Claude application is a model, some tools, and the code that decides what happens next. A workflow keeps that decision in your code. You name the stages, the branches, and the stop condition before the run starts. Claude fills a language-shaped gap inside a stage: extract these fields, draft this note, classify this ticket. The path itself does not depend on the model inventing the next stage.

An agent inverts the ownership. You give the model a goal and a tool list. The model chooses which tool to call, in which order, and when it is finished. Your code still runs the tools and still decides whether a call is allowed, but the route through the task is chosen at runtime. One model in a tool-use loop is already an agent. Agent does not mean a fleet of agents.

The agent loop

An agent loop is control flow, not a sentence in the prompt. Each turn sends the current messages, reads the response, and either stops or continues. The field that decides is stop_reason. tool_use means the application runs the requested tools, appends the results, and calls again. end_turn means the model is finished and the loop returns the content.

The application executes the tools. Claude does not. The tool result goes back as a user turn, which is why the history grows on every pass. A text block that says the work is done is not a stop signal. The same response can contain prose and a tool call. An iteration cap is a ceiling so a runaway loop cannot spend without bound. It is not how you detect completion.

while (turns < MAX_TURNS) {
  const response = await client.messages.create({ model, tools, messages });
  if (response.stop_reason === "end_turn") return textFrom(response);
  if (response.stop_reason !== "tool_use") throw new Error(response.stop_reason);
  messages.push({ role: "assistant", content: response.content });
  messages.push({ role: "user", content: runTools(response) });
  turns += 1;
}

Decision criteria

Prefer the simplest structure that meets the requirement. Start at a single model call. Move to a workflow when you need several fixed stages. Move to an agent only when you cannot enumerate the route in advance and that non-determinism is acceptable.

A validation failure you already know about is not a reason to become an agent. "If the vendor is missing, reject the row" is a branch you can write. An agent earns its place when the follow-up itself is unknown: the lookup may reveal a fraud hold, a partial shipment, or a contract exception, and each of those opens a different investigation you cannot list at design time.

Two further signals keep a borderline task as a workflow. If a wrong step is expensive, you want a guard between named stages. If operators need to see the path in ordinary traces, a fixed pipeline is easier to follow than a transcript of model-chosen tool calls.

• Known, identical steps on every run: workflow. Cheaper, faster, and testable stage by stage.
• Path depends on discoveries: agent. You pay in extra turns, variable cost, and harder tests.
• Either structure would work: workflow. Autonomy that the task does not need is a defect.
• A single tool-use loop is an agent. Do not demand a multi-agent design to justify the word.

Supervisors, subagents, and decomposition

A manager or supervisor hierarchy is for a task that is too wide for one context, or that splits into jobs with different tools. The supervisor owns decomposition, delegation, aggregation, and the decision to stop or ask a human. Each subagent receives a bounded goal and the slice of context it needs. It does not inherit the supervisor's transcript, and it does not message its peers. Results return to the supervisor, which is the only place a cross-cutting decision is made.

Task decomposition is the supervisor's job. A thin report that misses whole categories is a decomposition failure: the workers did the slice they were given. Widen the split, or send the gap back out. Do not blame the specialist that was never assigned that slice.

Isolation is the point of the subagent, not an inconvenience. A research worker can read dozens of files. The supervisor should receive a short finding with sources, not the file contents. That is how a hierarchy stays inside a context budget. The cost is explicit handoff: anything the worker must know has to be in its prompt.

Sequential and parallel execution

Sequential execution is the right shape when step N consumes the output of step N−1. Invoice extraction, then schema validation, then a ledger write is sequential even when each stage calls Claude. Running them at the same time would write a row from an extraction that has not been checked.

Parallel execution is for independent slices that share no intermediate state. Classifying four unrelated tickets, or researching solar and geothermal as separate questions, can run together. Wall-clock time drops. Token cost does not: you still pay for every call. Fan out only the work that does not need the other results. The supervisor fans in, then does the synthesis that actually depends on all of them.

A hybrid is normal. Independent investigations run in parallel. The synthesis that combines them is sequential and waits. Putting the synthesis in the parallel phase produces a report that ignores a still-running worker.

What you are trading

Reliability is about whether the same input produces an acceptable result, and whether a failure is visible. A workflow fails at a named stage you can unit-test. An agent can take a path you never exercised. You buy reliability back with hooks, evals, and a bounded tool list, not by adding more agents.

Predictability is whether operators can say what will happen before the run. Workflows are predictable because the graph is yours. Agents are predictable only at the boundaries you coded: which tools exist, which calls a hook will block, and when the loop must stop.

Cost scales with model turns and with how much history each turn resends. An agent that explores pays for wrong branches. A workflow pays a fixed number of calls. Parallelism lowers latency and raises concurrent spend. Context pressure is the hidden cost: long tool logs make later turns worse and more expensive. Keep raw exploration in a subagent and return a summary.

Receipts into a ledger

Every receipt takes the same path: OCR, extract amount and vendor, validate against the chart of accounts, write the row. A validation failure is a known branch: reject or queue for a clerk. That is a workflow. An agent would spend turns re-deciding an order that never changes, and the cost per receipt would vary for no benefit.

The tell that flips the design is a document that might be a receipt, a contract, or a claim, where the follow-up lookup depends on which kind it is and cannot be listed up front. That path is an agent, still with a code gate in front of the ledger write.

A support case with an unknown cause

A customer writes "the charge looks wrong." The next lookup might be the order, the invoice, a promo, or a duplicate charge, and that choice depends on what the first lookup returns. The investigation is an agent. The refund itself is not. A hook or a prerequisite check blocks the refund tool until a verified customer and an amount inside policy exist. The investigation can be autonomous. The money movement cannot.

Six energy types, one report

A supervisor splits "renewable generation" into solar, wind, geothermal, hydro, biomass, and storage. The six research slices share no state, so they run in parallel. Each subagent returns findings with sources. The supervisor then writes the comparison, which is sequential because it needs every slice. A report that covers only solar and wind is a decomposition miss on the supervisor, even if those two subagents were thorough.