Agent Architectures

Anatomy of an Agent

Six named parts: assembler, model, parser, executor, memory, and stop. The loop is the product.

The Assembler Has a Budget

The assembler decides what the model may see. Dumping the whole week plus 40 tool docs is how attention dies.

Parse, Then Fail Closed

The model emits text. JSON plus a schema is a decision. Unknown names and broken JSON do not run.

Stop Conditions and Budgets

Success, max steps, max dollars, max wall time, or handoff. Without stop, you bought a furnace.

ReAct: Thought, Action, Observation

The classic loop: reason, call a tool, read the result, repeat. Implemented here with a fake model.

Observe Before You Finish

A finish that ignores the last observation is a guess. The loop must read the world before it claims success.

Plan and Execute

Write a short plan first, then run steps. Better for multi-hop work; worse when the world changes under you.

Plans Are Data, Not Poetry

A plan is a list of typed steps with ids. Free-text paragraphs cannot be skipped, retried, or shown in a UI.

Reflection and Self-Critique

A second pass that scores the draft against a checklist. It is not a second personality — it is a function.

Ground the Critic

A critic that cannot see citations, tests, or policy will rubber-stamp vibes. Give it the same evidence the user will see.

Working Memory in the Loop

Scratchpad, rolling summary, and retrieve-on-demand. The loop uses stores; it is not one vector soup.

Typed State Beats a Blob

A dict with allowed keys is a contract. A giant string named state is how illegal tools sneak in.

State Machines for Agents

Named states, allowed tools per state, and guards on transitions. Graphs you can draw beat loops you cannot.

Human in the Loop

Pause before irreversible tools. The human sees a frozen payload. They do not become a free-text second model.

Freeze the Approval Payload

Args at pause time are the contract. Resume must not pick up mutated dicts or extra keys from later thoughts.

Long-Running Agents

A job with a store and a wakeup, not a request that holds a socket for an hour.

Checkpoints You Can Replay

Save typed state after each step. Replay from a checkpoint instead of restarting the whole furnace.

Error Recovery

Timeouts, retries with a cap, circuit breakers, and fail-closed. Recovery is policy, not vibes.

Computer Use in the Loop

A screenshot grid is a last resort. Prefer an API. If you must click, bound the grid and never click pay.

Router, Specialist, Verifier

Small agents with jobs beat one god-loop. Route first, specialize second, verify before the world changes.

Traces You Can Debug

Every step logs assembler budget, raw model text, parse result, tool, observation, and stop reason.

Detect Tool Thrash

The same tool with the same args three times is a bug. Stop, do not pay for a loop inside the loop.

Handoff Is a First-Class Stop

Unknown, unsafe, or over-budget work goes to a human or another system with a packet, not a shrug.

When Not to Agent

If a checklist, a form, or a search box will do, ship that. Agents are for branching work — and they are next to multiagent, not instead of a script.