Originally published on my site: https://sheikhwasim.com/insights/agent-architecture-five-layer-stack/
Most "AI agents" fail for the same reason.
Someone wires a language model to a handful of tools, demos a happy path, and calls it architecture. It works in the slide. It collapses the first time production is messy timeouts, bad inputs, spend spikes, irreversible side effects.
Here's the five-layer stack that actually ships.
Quick use case
Situation. A team built an internal "support triage agent." Demo day looked sharp: read a ticket, call search, suggest a reply, update CRM status.
What broke. In production, one vague ticket sent the agent into a 40-step tool loop. It wrote the wrong CRM status, and spend spiked past the monthly budget in an afternoon. Chat logs showed answers — not which tool ran, with what inputs, or why it kept going. The CRM write couldn't be cleanly reversed.
The fix (mapped to the stack).
- Orchestrator — hard max steps + stop when confidence is low
- Tools — typed CRM update with auth scope + idempotency key
- Traces — every plan / tool call / result / cost on one correlation ID
- Guardrails — daily spend cap + deny list for irreversible tools without a human gate
- Rollback — compensating "revert status" action when the write was wrong
Same model. Different system. That's the difference between a demo and something teams can trust.
Layer 1 — Orchestrator
The orchestrator decides the next step. It is not the model dumping text forever.
Good orchestrators:
Tools are clear APIs, not mystery side effects.
Ship-ready tools have:
- Auth and scoped credentials
- Typed inputs and validated outputs
- Timeouts, rate limits, and idempotency keys
- Explicit success / failure contracts
A tool that "usually works" is a liability. Prefer boring interfaces over clever ones.
Layer 3 — Traces
Every step logged so you can see what it did — and why.
Traces are how you debug, audit, and improve:
- Prompt / plan / tool call / result / decision
- Timing and cost per step
- Correlation IDs across services
- Redaction for secrets and PII
If you can't replay the path, you can't trust the system in an enterprise.
Layer 4 — Guardrails
Budget, permissions, PII, and stop conditions — before it runs wild.
Guardrails belong in the control plane, not in a polite system prompt:
If it's wrong, you reverse it. Idempotent actions beat clever guesses.
Design for undo:
- Prefer reversible writes
- Snapshot before mutate
- Compensating transactions when undo isn't free
- Clear "blast radius" for every tool
An agent that can't roll back isn't a system. It's a demo with confidence.
The test
Ask one question of any agent stack:
Can it show traces, and can it roll back?
If either answer is no, keep it out of production.
Closing
I'm Wasim Sheikh — AI Architect. I build systems teams trust and organizations depend on: not demos, not proofs of concept — production.
Follow for practical AI architecture that ships.
Site: https://sheikhwasim.com · Notes: https://practicalainotes.substack.com/ · X: https://x.com/anciwasim
- Spend and token caps
- Allow / deny lists for tools and data
- Human gates for irreversible actions
- Policy checks on inputs and outputs
Prompts are guidance. Guardrails are enforcement.
Layer 5 — Rollback
- Choose among plan act verify → stop
- Bound loop length and retry policy
- Separate "thinking" from "committing"
- Fail closed when confidence or evidence is weak
If your system can't explain why it took the next action, you don't have an orchestrator — you have a chat session with plugins.
Top comments (0)