“Agent” may be the most overloaded word in technology this year. Some people mean a chatbot with a few plugins. Others mean software that can run a business process end to end. Under the marketing, almost every AI agent does the same thing: it runs a loop. It takes a goal, thinks about it, uses a tool, looks at what happened, and decides what to do next, again and again until the job is done or it asks for help.
The research idea behind most of today’s agents is simple. The 2022 ReAct paper (published at ICLR 2023) proposed using language models “to generate both reasoning traces and task-specific actions in an interleaved manner, allowing for greater synergy between the two.” Think, act, observe, think again. Everything else is engineering around that loop.
This article draws that loop as ten capsules. The size of each capsule shows how much complexity it hides, on my own illustrative scale. The point of drawing it this way is practical: the big capsules are where agents fail, and where your design effort should go.
Figure 1. The agent loop as ten capsules. Capsule size and the dots show relative complexity (the author’s illustrative scale). Steps 3 to 10 repeat until the goal is met.
The ten capsules
1. Goal intake (small). The agent receives a request: “Find out why last night’s data loads failed and fix what you safely can.” Small, but not trivial. A vague goal produces a vague agent, so good systems restate the goal and its limits before starting.
2. Context and memory (medium). What does the agent already know? It gathers relevant documents, past conversations, system state and notes from earlier runs. Most “the agent hallucinated” stories are really “the agent had the wrong context” stories.
3. Planning (large). The agent breaks the goal into steps: list the failed jobs, read their error logs, group them by cause, fix the safe ones, report the rest. This is the first big capsule. A bad plan wastes every step after it, and a plan that is too rigid cannot adapt when step two reveals a surprise.
4. Tool selection (small to medium). For the current step, which tool fits: a database query, a log search, a code runner, an email? Agents are only as capable as the tools they are given, and only as safe as the tools they are denied.
5. Guardrail check (medium). Before acting, is this action allowed and safe? Does it touch production? Is it reversible? Does it need a person’s approval? This capsule is easy to skip in a demo and essential in real use.
6. Act (small to medium). The agent calls the tool. The call itself is usually simple; the risk lies in what it changes.
7. Observe (small). The agent reads the result: rows returned, an error message, a file written.
8. Evaluate and reflect (large). Did that work, and if not, why not? This is the second big capsule, and the one that separates useful agents from expensive ones. The 2023 Reflexion paper showed one way to strengthen it. Its agents “verbally reflect on task feedback signals, then maintain their own reflective text in an episodic memory buffer to induce better decision-making in subsequent trials.” In plain terms, the agent writes itself a note about what went wrong and reads it before trying again.
9. Update memory (small to medium). The agent keeps what it learned, such as “job X fails when the upstream file arrives late,” so the next run starts smarter.
10. Finish, loop or hand off (medium). Is the goal met? If not, go back to planning. If the agent is stuck, or the next step is risky, hand off to a human with a clear summary. Knowing when to stop is a feature, not a failure.
Why capsule size matters
When you draw an agent this way, a pattern jumps out. The complexity is not in the tool call, the part most demos show. It concentrates in three places: context, planning and evaluation. That is where agents go wrong, and it tells you where to spend your engineering effort.
- Context and memory. What typically goes wrong: stale, missing or irrelevant information. Design tip: retrieve narrowly; record where each fact came from.
- Planning. What typically goes wrong: plans that are too long, too rigid or aimed at the wrong goal. Design tip: plan a few steps ahead, then re-plan after each observation.
- Guardrail check. What typically goes wrong: actions that are irreversible or out of scope. Design tip: list what the agent may never do; require approval for irreversible steps.
- Evaluate and reflect. What typically goes wrong: the agent declares success too early, or loops forever. Design tip: define “done” up front; cap retries; check results against evidence, not the agent’s own opinion.
- Finish or hand off. What typically goes wrong: silent failure, or an unhelpful “I could not complete this”. Design tip: hand off with what was tried, what was learned and what is needed.
A worked example: one agent, one night of failed data loads
Here is the loop on a problem every data team knows. Two overnight data loads have failed.
- Goal intake. Find the causes, and safely rerun what can be rerun.
- Context. The agent pulls the job schedule, the last run statuses and the runbook.
- Planning. It lists the failed jobs, reads each error, groups them by cause, reruns only the jobs whose cause is known to be transient, and reports the rest.
- First failure: a timeout. The agent chooses the log-search tool. The guardrail check passes, because reading logs is safe. It acts, observes a timeout error, and evaluates: timeouts on this job are known to be transient. It reruns the job, which requires another guardrail check: reruns are allowed for this job type, so it proceeds. It observes success.
- Second failure: a schema change. A new column appeared upstream. The evaluation step recognizes this as not safe to fix automatically. Changing a table definition is out of scope.
- Finish and hand off. The agent writes a summary: one job rerun successfully, and one needs a person to approve a schema change, with the evidence attached. It records the lesson in memory.
No step was magic. The value came from the big capsules: good context, a plan that adapted, and an evaluation step honest enough to stop.
A checklist before you build or buy an agent
- Goal: can the agent restate the goal and its limits?
- Context: where does its information come from, and how fresh is it?
- Plan: does it re-plan after surprises, or push on regardless?
- Tools: does it have only the tools it needs?
- Guardrails: what can it never do, and what needs approval?
- Evaluation: how does it know it succeeded, other than saying so?
- Hand-off: when it gets stuck, does it hand off to a person with a useful summary?
- Memory: does it get better over time, and can you inspect what it remembers?
The takeaway
An AI agent is not a mysterious digital employee. It is a loop of ten capsules, and three of them — context, planning and evaluation — hold most of the complexity. Draw your agent this way before you build it. The sizes of the capsules tell you where it will break, and where your engineering hours will pay off.
References
- S. Yao, J. Zhao, D. Yu, N. Du, I. Shafran, K. Narasimhan and Y. Cao, “ReAct: Synergizing Reasoning and Acting in Language Models,” ICLR 2023. arXiv:2210.03629
- N. Shinn, F. Cassano, E. Berman, A. Gopinath, K. Narasimhan and S. Yao, “Reflexion: Language Agents with Verbal Reinforcement Learning,” 2023. arXiv:2303.11366
Capsule sizes reflect the author’s judgment and are illustrative, not measured. The views expressed are the author’s own.
I used an AI writing assistant to help draft and edit this article. I reviewed and revised the text and checked every source.
Originally published on Medium.
Top comments (0)