AI & MCP
Orchestrating multi-step agents: plan, checkpoint and per-step budget
A multi-step agent holds up when the plan is a file, every step has a gate and the cost is capped before it starts. Here is the loop and where it breaks.
Key points
- The plan lives on disk with per-step state, so an interruption does not restart from zero.
- Every step has a runnable gate and a call cap, otherwise the loop never terminates.
- MCP offers no transactions: tools that write need an idempotency key inside the tool.
A multi-step agent is orchestrated with a written plan, an on-disk checkpoint and a per-step budget, not with a longer prompt. The model picks the action inside a step; the shape of the loop stays in your code.
The minimal loop
Four states are enough: plan reads the plan, step runs a single action, gate checks the result with a command, checkpoint writes the state to disk. If the process dies at step 7, the restart reads the checkpoint and resumes at step 7, not at step 1.
The plan is a file, not a message
{
"goal": "aggiungere il filtro regione al catalogo",
"budget_calls": 40,
"steps": [
{ "id": 1, "action": "search_components", "gate": "results > 0" },
{ "id": 2, "action": "edit", "files": ["client/src/pages/Components.tsx"], "gate": "npm run build" },
{ "id": 3, "action": "verify", "gate": "npx tsc --noEmit -p client/tsconfig.json" }
]
}The plan declares the maximum number of calls before the run starts. A written cap is the only defence against a loop that keeps trying to fix the same error: when the calls run out, the agent stops and leaves you the diff.
One step, one call
curl -s https://ui.eneawork.it/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_components","arguments":{"query":"table filter","limit":5}}}'The response is text: the server does not know which step you are running and does not see the rest of the conversation. Your code has to record the tool name, the arguments and the duration, because the model will not, and without that log you cannot explain a failure.
Where it breaks
| Failure | How it shows up | Guard |
|---|---|---|
| Step run twice | two files written with the same content | idempotency key in the tool argument |
| Plan drifting | step 7 talks about another file | frozen plan and a diff between plan and action |
| Context growing | cost per step climbing | summarise every five steps, drop old outputs |
| Rate limit | a 429 error mid-loop | backoff with a cap and a counter in the checkpoint |
| Slow tool | one step takes minutes | per-call timeout and the step marked failed |
The verifier is not a second opinion
A second agent saying “looks fine to me” verifies nothing. The useful verifier runs a command and compares an output: build, types, tests, expected diff. If the check is an opinion, you are paying two models for the same mistake.
The limitation
MCP has no transactions. A call that writes cannot be rolled back, and a retry after a timeout can duplicate the effect: idempotency belongs in the tool, not in the client. The EneUI server is read-only, so the pattern described here is safe for discovery and reads, not for writing to an external service.
Where to continue
The system prompt is covered in prompts for agents, the shape of a skill in anatomy of an agent skill, and the cost per task in evaluating a model for code. For the server side read building an MCP server. The catalogue the example draws from is 111,985 components and 1,556 blocks; an MIT record suited to an agent UI is dqnamo agent dock.
Frequently asked questions
How many steps should an agent have at most?
There is no right number, only an explicit cap. The plan must declare a maximum number of calls and stop there: without a cap the loop keeps retrying the same error and the cost grows with no result.
Do I need a database for checkpoints?
No, an atomically rewritten JSON file is enough for a single agent. A database matters when two processes work on the same plan, because then the checkpoint becomes a lock.
How do I handle the MCP server rate limit?
With backoff and a counter in the checkpoint. The EneUI anonymous tier allows 60 requests per minute, free 120, pro 600 and team 1,200, values read in backend/entitlements.js on 1 November 2026.
Must the verifier be another model?
Not necessarily. It must run a command that can fail: build, types, tests or a comparison with an expected diff. A second model that reads and approves adds cost and no evidence.
Can the agent write through MCP?
Only if the writing tool is idempotent, because MCP has no transactions and a retry can duplicate the effect. The EneUI server is read-only, so that risk does not exist there, but a write tool must survive a double submit.