The Agentic Prompt Stack: 6 Layers for Designing Prompts That Run Agents

Key takeaways:

• Agents fail differently from one-shot prompts. They drift over steps, call tools with bad arguments, forget instructions, and repeat themselves. A flat prompt cannot be debugged by those symptoms; a layered stack can.
• Six layers, each owning one concern: Goals, Tool permissions, Planning scaffold, Memory access, Output validation, Error recovery.
• Layers 5 and 6 are the most under-built in practice. Teams ship agents without real output validation or error recovery and discover the gap in production.
• The stack is a design tool and a diagnostic tool. Use it to draft an agent prompt; use it again when something breaks to figure out which layer to fix.
• Pair it with the SurePrompts Quality Rubric for the prompt-level audit and with RCAF for the underlying drafting skeleton inside individual layers.

Why agent prompts need a stack, not a structure?

One-shot prompts succeed or fail in one call. A skeleton like RCAF — four labeled slots, one pass, done — fits them cleanly.

Agents do not work like that. An agent runs for many steps, calls tools, accumulates observations, and decides what to do next based on what it has done so far. Failures happen across steps:

• Agent stops before finishing. (Goal problem.)
• Agent calls a tool with malformed arguments. (Tool-permission problem.)
• Agent loops, repeating the same action. (Planning-scaffold problem.)
• Agent forgets an instruction from five steps ago. (Memory problem.)
• Agent returns a result in the wrong shape. (Output-validation problem.)
• Agent crashes when a tool fails. (Error-recovery problem.)

Each failure maps to a distinct concern. A flat skeleton cannot diagnose them because the failure is not in "the prompt" — it is in one of six responsibilities. The Agentic Prompt Stack gives you six. RCAF is still the right skeleton inside each layer, especially Layers 1 and 5. The Context Engineering Maturity Model sits underneath, handling how context is assembled on every step. For the coding-agent application, see the complete guide to prompting AI coding agents.

The six layers

Layer 1 — Goals

What it is. What the agent is trying to achieve, what counts as success, and what is out of scope. The agent's contract with the outside world.

What goes in the prompt. A one-sentence goal. A success criterion the agent can check ("the report file exists and contains at least three cited sources"). A short "not in scope" list. Any global hard constraints ("never send email without explicit confirmation").

Example: Your goal is to produce a 500-word research brief on the given topic, saved to brief.md, with at least three distinct sources cited inline. You are done when the file exists and passes the citation check. Out of scope: editing any other file; calling any tool more than 20 times.

How it fails. Agent finishes too early, too late, or drifts. Non-terminating loops are almost always goal failures — no signal for "stop."

How to debug. Could the agent write a boolean check for "am I done?" If fuzzy, fix Layer 1.

Layer 2 — Tool permissions

What it is. Which tools the agent can call, with what argument shapes, under what conditions. Where destructive failures originate and where the agent's blast radius is defined. This is where tool use and function calling live.

What goes in the prompt. Enumerated allowed tools with argument schemas and preconditions. For each tool, when it applies. An explicit default: if a tool you need is not listed, do not guess — report and stop.

Example: Allowed tools: web_search(query: string), fetch_url(url: string), write_file(path: string, content: string) restricted to files matching brief*.md. Never call write_file on any other path. Never call a tool not listed above.

How it fails. Agent invents a nonexistent tool. It calls a real tool with a malformed argument. It calls an allowed tool in a forbidden context. It refuses a tool it should use because the permission text was ambiguous.

How to debug. Inspect the last three tool calls. Wrong arguments mean the schema is underspecified. Missing calls mean the "when to call" rule is unclear.

Layer 3 — Planning scaffold

What it is. How the agent structures intermediate reasoning between steps. Common scaffolds: ReAct (interleaved thought, action, observation), plan-and-execute (plan up front, execute, reflect), tree-of-thoughts, self-refine. Pick one and be explicit.

What goes in the prompt. A named scaffold and its turn-by-turn shape ("at each step: THOUGHT — current state and next sub-goal; ACTION — one tool call; OBSERVATION — verbatim tool result"). A completion signal mapped back to Layer 1 ("when the goal is met, emit FINAL: and stop"). For anything beyond trivial, we prefer plan-execute-reflect over single-shot ReAct: the plan anchors against drift, the reflect step catches silent failures.

How it fails. Agent skips the thought step and calls tools reactively. It reasons verbosely but never acts. It acts without reasoning. It forgets the scaffold partway through a long trajectory.

How to debug. Read the trace. If the scaffold's sections are missing or collapsed, the prompt describes the scaffold instead of modeling it. One worked THOUGHT/ACTION/OBSERVATION example in the system prompt usually fixes this instantly.

Layer 4 — Memory access

What it is. What the agent recalls across steps, how memory is committed, what is summarized vs stored verbatim. In agents, memory is a managed resource with explicit read and write operations — not conversation history.

What goes in the prompt. The memory surfaces available (scratchpad, persistent user memory, retrieved documents). How to commit facts worth remembering. What gets summarized. What never leaves the current step.

This is where the Context Engineering Maturity Model meets the agent: Level 3 rebuilds context every step; Level 4 commits to a memory layer with explicit policy; Level 5 budgets memory access against the context window.

How it fails. Agent forgets a fact from five steps ago. It writes everything and drowns in noise. It treats stale observations as authoritative. It hallucinates its own prior actions.

How to debug. Does the failing behavior hinge on remembered info? Recomputation means the write rule is too narrow; confusion by stale data means the read rule is too permissive. Symptoms cross most with Layer 3 — weak scaffolds often get blamed on memory.

Layer 5 — Output validation

What it is. The shape the agent's outputs must take and how they are checked — final and intermediate tool-result handoffs. Where structured output, schema validation, and self-critique steps live.

What goes in the prompt. The exact schema for every structured output (usually JSON with typed fields). A self-critique step before finalizing ("before emitting FINAL, check: all required fields present, no placeholder text, all cited URLs actually appeared in observations"). Wrap the model call in programmatic validation. If schema parsing fails, do not trust the agent to self-correct — reject and retry with the specific failure reason. Prompt carries the schema; runtime enforces it.

How it fails. "Almost JSON" — trailing commas, prose preamble, missing fields. Fabricated fields. Placeholder text ("fill in the actual number here"). Most dangerous: output parses and looks right but is semantically wrong.

How to debug. Shape-wrong means the schema is not enforced programmatically. Shape-right but content-wrong means the self-critique step is missing or too generic.

Layer 6 — Error recovery

What it is. How the agent handles tool failures, ambiguous inputs, planning dead-ends, and retries. The layer that separates a demo agent from a production agent. Almost always the most under-built.

What goes in the prompt. What to do on tool error ("log verbatim to SCRATCHPAD, reassess the goal, either retry with different arguments, try a different approach, or stop and report"). A retry policy with a hard cap. Ambiguity guidance ("if the goal is ambiguous, ask one clarifying question; if still ambiguous, stop"). A give-up condition — a trajectory length or failure count that forces a stop.

How it fails. Agent retries the same failing call indefinitely. Ignores tool errors. Crashes on a null field. Infinite loops almost always involve this layer — no give-up means no exit.

How to debug. Force a failure. Healthy: error observed, logged, alternative considered, different approach or graceful stop. Under-built: same error, same retry, until trajectory budget runs out.

Summary table

How to debug an agent by layer

Pattern-match the symptom to the most likely failed layer. Heuristic, not exclusive.

• Stops mid-task claiming completion. Layer 1 — success criterion too loose.
• Runs past the point of completion. Layer 1 — no clear stop.
• Calls a tool with wrong arguments. Layer 2 — schema underspecified.
• Refuses a tool it obviously should call. Layer 2 — "when to call" guidance unclear.
• Repeats the same action infinitely. Layer 3 (no reflection forcing change) or Layer 6 (no give-up). Often both.
• Reasons verbosely but never acts. Layer 3 — scaffold rewards thought without requiring action.
• Acts without reasoning. Layer 3 — scaffold described but not modeled. Add a worked example.
• Forgets an instruction from five steps ago. Layer 4 — memory-write policy too narrow, or system prompt dropping from context on long trajectories. Cross-check with the Context Engineering Maturity Model.
• Invents a fact about its own prior actions. Layer 4 — memory-read treating summaries as authoritative.
• Returns malformed JSON. Layer 5 — enforce schema programmatically, reject and retry with the parse error.
• Returns well-formed but semantically wrong output. Layer 5 — self-critique missing or generic.
• Crashes on a tool error. Layer 6 — no error handling, no programmatic retry.
• Retries the same failing call 20 times. Layer 6 — no give-up, no alternative-approach instruction.

Two common misattributions: infinite loops blamed on "the model is stupid" (almost always Layer 1 or 6) and hallucinated tool calls blamed on the model's tool use (almost always a loose Layer 2 schema).

Worked example

Task. A research agent with web search and a save_to_file tool. Goal: produce a 500-word briefing.

Layer 1 — Goals. Produce a 500-word research brief on the given topic and save it to brief.md. Cite at least three distinct sources inline using [Source: URL]. Done when brief.md is 450–550 words and the citation check finds three or more distinct source URLs. Out of scope: modifying any other file; calling web_search more than ten times.

Layer 2 — Tool permissions. Allowed: web_search(query: string), fetch_url(url: string), save_to_file(path: string, content: string) restricted to path = "brief.md". If you need a tool not listed, stop and report.

Layer 3 — Planning scaffold. Emit an initial PLAN (3–5 numbered steps). Then at each step: THOUGHT — current state and next sub-goal; ACTION — exactly one tool call; OBSERVATION — the verbatim tool result. After the last step, a REFLECT block checking the plan was followed.

Layer 4 — Memory access. SCRATCHPAD is writeable. Record citable facts as FACT | claim | URL, dead ends as DEAD END | what you tried | why. Before each search, read SCRATCHPAD to avoid duplicates.

Layer 5 — Output validation. Before calling save_to_file, emit a VALIDATION block checking: word count 450–550; three or more distinct cited URLs; no placeholder text; every [Source: URL] refers to a URL that actually appeared in an OBSERVATION. If any fail, revise and re-check. Only save when all pass.

Layer 6 — Error recovery. On tool error, log ERROR | tool | error in SCRATCHPAD, then either retry with different arguments (max two retries per tool), try a different sub-goal, or emit FINAL with a partial brief and a LIMITATIONS: section. Hard stop at 30 steps.

Scored against the SurePrompts Quality Rubric this lands around 30/35, held back mostly by example quality inside Layers 1 and 2. The point is not the wording — it is that every failure mode you expect to see (malformed output, infinite search loops, silent tool errors, forgotten sources) maps to exactly one layer you can fix without rewriting the rest.

Our position

• Prefer plan-execute-reflect over single-shot ReAct for anything beyond trivial. ReAct alone is fine for trajectories under five steps; past that, the plan-and-reflect overhead pays back.
• Structured outputs plus programmatic schema validation are not optional at this tier. Let the runtime reject malformed output and feed the parse error back to the agent — do not trust the agent to self-correct on format.
• Layers 5 and 6 are the most under-built in practice. Teams ship with strong goals, tools, and scaffolds and nearly zero output validation or error recovery, then discover the gap when production traffic surfaces edge cases.
• For agent prompts, weight the SurePrompts Quality Rubric differently — output validation and constraint tightness count double; example quality and role clarity count less. Agents are judged on what they reliably produce across steps, not on whether one output reads well.
• Agents below Context Engineering Maturity Model Level 3 are fragile by construction. The memory discipline Layer 4 assumes is what CEMM Level 4 codifies.
• Treat Layer 6 as a first-class design problem, not a try/except wrapper. Budget the same design time on it as on the planning scaffold.
• For coding agents specifically, Layer 1's "out of scope" list and Layer 2's tool restrictions carry more weight than in research or operational agents. See the complete guide to prompting AI coding agents for the domain-specific version.

Related reading

• The Complete Guide to Prompting AI Coding Agents (2026) — pillar for coding-agent work.
• Agentic AI Prompting Guide — broader discipline this canonical sits within.
• AI Agents Prompting Guide — agent patterns across domains.
• Multi-Agent Prompting Guide — how N stacks compose.
• Plan-and-Execute Prompting — the Layer 3 scaffold we default to.
• ReAct Prompting Guide — the most common alternative Layer 3 scaffold.
• Tool Use Prompting Patterns — Layer 2 tactical companion.
• Self-Refine Prompting Guide — a Layer 5 self-critique pattern.
• Reflexion Prompting Guide — a Layer 6 error-recovery pattern.
• The SurePrompts Quality Rubric — the prompt-level audit.
• The RCAF Prompt Structure — drafting skeleton for individual layers.
• Context Engineering Maturity Model — infrastructure model underneath Layer 4.