The loop is the easy part — the state is not.
Most agent architectures look the same on a whiteboard: a model, some tools, a loop. What separates the agents that run in production from the ones that stall after a good demo is a set of decisions that never appear on the whiteboard at all. Every framework gives you the loop — the model proposes, a tool executes, the result is appended, repeat. That is a hundred lines of code and it is not where projects fail. The question that decides your architecture is what the agent knows at step N. Naively the answer is everything so far, the full transcript replayed into every call. This works beautifully in a demo with four steps and collapses at thirty: cost grows quadratically, latency with it, and the model's attention to the relevant part of the context degrades exactly as the task gets harder. The pattern that holds up is explicit state, separate from the transcript — a structured record of what has been established, what remains, and what was tried and failed, maintained deliberately and passed forward compactly, with the raw transcript kept for debugging rather than for reasoning. Treat the context window as a working set you curate, not a log you append to.
Tools are an API design problem, not a prompt problem.
When an agent uses a tool wrongly, the reflex is to edit the prompt. The prompt is usually not the problem; the tool is. Tools designed for agents differ from tools designed for programmers in three ways. Flat over nested: deeply structured arguments produce malformed calls, so prefer few parameters with obvious names and no optional-argument mazes. Errors are instructions: a tool returning 400 Bad Request teaches the agent nothing, while one returning start_date must precede end_date, you sent these two values, gets a correct retry — write error messages for the reader who will act on them. And narrow over general: one tool that does nine things via a mode flag will be called wrongly, where nine clearly named tools will not. Most conclusions that the model is not smart enough dissolve when the tool surface is redesigned.
Design for partial failure from the first commit.
A multi-step agent will fail mid-sequence, not occasionally but routinely, because it is calling real systems that time out, rate-limit and change under it. The architecture has to answer what the state of the world is after a failure at step four of six. Three patterns, in ascending order of cost and robustness: idempotent actions with retry, the cheapest and the one to design for first; checkpoint and resume, which persists state after each step and requires the explicit state described above; and compensating actions, an explicit undo for each forward action, expensive but necessary when steps are externally visible, since a message sent cannot be unsent, only followed by a correction. Choosing none of these is itself a choice — you have chosen silent partial completion, the most expensive failure mode to diagnose after the fact.
Approval gates belong in the architecture, not the prompt.
Telling an agent in its system prompt to ask before doing anything destructive is a preference, not a control. It will hold until the one context where it does not. Gates belong in the execution layer: an action is classified by impact, and high-impact actions cannot execute without an approval token regardless of what the model decided. The model proposes, the gate disposes. This is unglamorous plumbing and it is the single feature that most often determines whether an organisation will allow an agent near production systems. It also compounds well — an agent with real gates can be granted more authority over time as its track record accumulates, while an agent relying on prompt-level restraint cannot be granted anything.
If you cannot replay it, you cannot operate it.
When an agent does something unexpected, you need to reconstruct exactly what it saw, what it proposed, which tool ran, what came back, and why the next step followed. Without that, debugging is guesswork and every incident review ends in a shrug. Capture per step the input context, the model's output verbatim, the tool invoked with arguments, the raw result, and the elapsed time and token cost. This is also your evaluation dataset and your regression suite: the same traces that let you debug an incident let you verify a model upgrade before it ships.
Model choice is a routing decision, not a procurement one.
Treating which model as a single up-front decision is a category error. Different steps have different requirements — planning benefits from a stronger model, classification and extraction rarely do, and a well-scoped tool-selection step often runs perfectly on something small and fast. Build the model as a parameter of the step rather than a constant of the system. This cuts cost immediately and, more importantly, means the next model release is a configuration change and a regression run rather than a migration project.
What this adds up to.
None of the above is about the model. It is state management, API design, failure handling, access control and observability — ordinary distributed-systems engineering, applied to a component that happens to be non-deterministic. That is the actual lesson. Agents are not a new discipline; they are a new kind of unreliable dependency in a system you already know how to build carefully. Teams with strong engineering practice adapt to them quickly. Teams hoping the framework will supply the practice do not.