The agent hype makes it sound like the hard part is the loop โ give a model tools, let it think, act, observe, repeat. Building three small agents taught me the opposite: the loop is the easy part. The hard part is everything the model does not control.
The naive build:
System: You are a research assistant. Use tools to answer questions.
Loop: model โ tool call โ result โ model โ ...
It worked beautifully for one tool call. Then:
Question: "Compare the caching strategies in the docs"
Turn 1: search("caching strategy") โ great
Turn 2: read(doc A) โ great
Turn 3: read(doc B) โ fine
Turn 4: read(doc B) โ AGAIN, same doc
Turn 5: summarises from doc A only, never uses doc B's content
Failure mode: no working memory of what it has already done. The context window holds everything, but the model re-derives its plan from scratch each turn and doesn't track state.
Fix that worked: maintain an explicit plan and visited list in the system prompt, updated every turn by code, not the model:
You have read: [docA, docB]
You have NOT read: [docC]
Your plan: 1) โ gather docs 2) โ compare 3) write summary
Success rate on 5-step tasks went from ~40% to ~80%. The model is a great executor of a plan it can see โ a bad keeper of one.
The exciting one. Give it a failing test and let it work.
What it did right, surprisingly well:
- Read the test, found the relevant file, identified the off-by-one
- Made the edit, ran the test, confirmed green
- Explained the fix clearly
What broke it:
Edit 1: fixed the off-by-one โ
Edit 2: "while I'm here, cleaned up..." โ introduced a regression
Test: fails differently now
Agent: "Let me revert my cleanup" โ can't, it doesn't know
which lines were its cleanup
Test: still failing
Agent: gives up / loops
Failure mode: it cannot separate its own changes from the environment. Every edit is context, not its edit, with no ownership tracking.
Fixes that worked:
- One edit per turn, mandatory test run โ the harness, not the model, enforces the loop:
edit โ run tests โ report result โ decide
- Git as external memory โ after each edit,
git add -A && git commit -m "agent: step N". Reverting becomes git revert instead of reconstructing.
- Stop conditions in code โ max 5 steps, or abort. An agent without a leash is a cost center that apologizes.
[!WARNING]
- An agent that can edit files and run commands is a security surface. My bug-fix agent's sandbox was a throwaway container with a mounted copy of the repo, no network, no credentials. The day an agent has real credentials and a "just fix this" prompt is a prompt-injection incident waiting to happen.
The "realistic" agent: create ticket, update CRM, schedule, notify. The interesting finding: with 8 tools, tool selection became the bottleneck.
- 30% of failures were choosing the wrong tool for the task (
update_ticket_status vs update_crm_stage โ similar names, different semantics)
- The model would sometimes invent a tool name that didn't exist. The framework handled it; the task died.
Fixes that worked:
- Tool descriptions are the API docs. I rewrote each tool's description to include when NOT to use it and one example. Tool-selection accuracy went from ~65% to ~90%.
- Reduce the toolset per phase. Instead of 8 tools always available, the workflow gates: intake phase sees 3 tools, execution phase sees 4. Smaller choice sets beat better models.
The Boundary Map (My Honest Summary)
| Task length | Reliability | Notes |
|---|
| 1โ2 tool calls | Very high | This is where agents genuinely shine |
| 3โ5 tool calls | Good, with scaffolding | Explicit plans, git, stop conditions |
| 6+ tool calls | Fragile | Errors compound; needs checkpointing + human review |
| Long-horizon / multi-session | Not yet | Memory, planning, and self-correction still fail |
- Scaffold more than you prompt. The external state (plan, visited, git, stop conditions) matters more than the system prompt.
- Small toolsets with great descriptions beat big toolsets with great models.
- Every tool call is a trust decision. Agents need the same least-privilege thinking as any service account.
- Evaluate the loop, not the answer. "Did it finish" is not the metric โ "did it do N steps correctly in order" is.
- The boring engineering wins. Checkpointing, retry policy, timeout, audit log. None of it is AI. All of it determines whether an agent is a product or a demo.
Discussion (0)
Sign in or create an account to join the discussion.
No comments yet. Start the discussion.