Prompt Engineering for AI Agents: What's Different in 2026

Most people who have been prompting chatbots assume that skill transfers cleanly to agents. It does not. A well-crafted message to a chatbot and a well-crafted system prompt for an autonomous agent are not the same thing. They are not even close. The mental model you built for getting better answers from ChatGPT will mislead you when you try to apply it to an agent that runs for twenty steps, calls six tools, and makes decisions you never anticipated.

This guide is for people who already understand what agents are and want to get much better at actually prompting them. We will cover what makes agent prompting structurally different, how to design each part of the prompt stack, and the specific mistakes that cause agents to fail in repeatable, fixable ways.

Why agent prompting is not chatbot prompting

A chatbot prompt sets the tone for a single exchange. You write a message, the model responds, done. Even with a system prompt, the model's job is to produce one coherent reply and stop.

An agent's system prompt does something else entirely. It has to govern behavior across an unpredictable sequence of steps. The model will read that system prompt not once but on every iteration of the loop. It will make tool calls it infers from that prompt. It will decide when to stop based on what the prompt implies about completion. It will handle errors, unexpected tool outputs, and edge cases the prompt author never thought to describe.

The chatbot prompt answers: how should the model talk?

The agent system prompt answers: how should the model decide? That is a harder question, and it requires a different approach.

A common illusion is that a clever persona ("you are a helpful assistant who always thinks step by step") is sufficient. For a chatbot, that works reasonably well. For an agent doing real work, that kind of prompt leaves the model making dozens of micro-decisions with no guidance. Some of those decisions will be fine. Others will cause the agent to hallucinate a file path, delete something it should not touch, or loop forever because it does not know what "done" looks like.

The parts of an agent prompt stack

Agent prompting is not a single prompt. It is a stack of prompts that work together:

1. System prompt - the standing instructions that define the agent's identity, scope, constraints, and operating rules.
2. Tool descriptions - the text attached to each tool definition, which the model uses to decide when and how to call each tool.
3. Task prompt - the specific goal handed to the agent for a given run.
4. Planning prompts - intermediate prompts that ask the agent to reason through a plan before acting.
5. Reflection prompts - prompts injected after a step (or after failures) to ask the agent to evaluate what happened.

Most of the tutorials you find online focus only on item one. The rest get ignored, and that is why agents built from tutorials behave so differently from agents built by teams who have shipped them to production.

How to design a system prompt for an agent

A good agent system prompt covers four things: role, scope, constraints, and stopping conditions.

Role is not just "you are an X." It should specify what the agent is responsible for and what it is not responsible for. "You are a code review agent. Your job is to identify bugs and style issues in Python code submitted by users. You do not modify files unless explicitly asked. You do not execute code." That kind of specificity prevents a class of errors that a vague persona cannot.

Scope tells the model what resources and actions are available. If the agent has access to a file system, the system prompt should describe what part of the file system it operates on, what it can read, and what it can write. Leaving this implicit means the model will infer scope from context, and it will sometimes infer wrong.

Constraints are the explicit rules the agent must follow. These should be concrete and testable. "Never call the database tool more than five times in a single run" is a real constraint. "Be careful with data" is not. Vague constraints do not constrain behavior, they just add noise.

Stopping conditions tell the agent what completion looks like. This is the most neglected part of agent system prompt design. Without a clear definition of done, agents will either stop too early (because nothing in the prompt told them to keep going) or run forever (because nothing told them when to quit). Good stopping conditions are specific: "The task is complete when you have produced a summary file named output.txt. Do not produce additional files or continue looping after that file is written."

Claude Code is a useful reference here because Anthropic publishes a lot of detail about how they structure system prompts for that agent. The separation between what Claude Code will and will not do autonomously is encoded directly in the system prompt, not left to intuition.

Writing good tool descriptions

Most developers write tool descriptions as documentation. "This tool searches the web. Input: query string." That is technically correct and practically useless.

A tool description for an agent prompt needs to answer: when should I use this tool, and when should I not? The model is making a selection decision every time it considers a tool call. A description that only explains what the tool does skips the part the model actually needs.

Better tool description structure:

• What the tool does (one sentence, direct)
• When to use it (specific conditions or triggers)
• When not to use it (explicit exclusions if there is risk of misuse)
• What the output looks like (helps the model interpret results correctly)
• Known limitations or failure modes (prevents over-reliance)

For example, instead of "Searches the codebase for a string. Input: query," write: "Searches the codebase for a string using grep. Use this when you need to find where a function, variable, or pattern is defined or referenced. Do not use this as a substitute for reading a file you already know the path to. Returns a list of file paths and line numbers. May return many false positives for short or common strings."

That description gives the model enough information to make a real decision. The first version does not.

This matters more than most people expect. Bad tool descriptions are one of the most common causes of agents making unnecessary calls, calling the wrong tool for a task, or misinterpreting tool output.

Planning prompts

Some agents just act. They pick the next tool call based on the current state and the goal, and they keep going. That works for short, simple tasks. It breaks down on anything multi-step, because the model can get locked into a local path that seemed reasonable at step two but leads somewhere wrong by step eight.

Planning prompts ask the model to think through a sequence before taking the first action. The most common form is a system prompt instruction like: "Before you start executing, write out a step-by-step plan for how you will complete the task. List the tools you expect to use and in what order. Then execute the plan, updating it if circumstances change."

This is not magic. The model can still produce a bad plan. But it catches a category of errors where the model starts doing things without thinking about the overall shape of the task. It also gives you a visible artifact (the plan) that you can inspect when something goes wrong.

LangGraph formalizes this pattern by separating planning nodes from execution nodes in the graph. If you are using LangGraph, that separation is already built into the architecture. If you are building a simpler agent without a framework, you get the same benefit by adding a planning step explicitly to the system prompt.

One thing to watch: planning prompts can cause agents to over-plan. If the task is simple, asking for a detailed plan before acting is waste. Reserve planning prompts for tasks that genuinely benefit from them, which usually means tasks with more than five steps, tasks that involve irreversible actions, or tasks where the agent has to choose between competing approaches.

Reflection prompts

Reflection is the other side of planning. Where planning prompts happen before action, reflection prompts happen after, usually after a failure, an unexpected result, or a completed step that changes the situation.

A reflection prompt asks the model to evaluate what just happened before deciding what to do next. Simple version: "You just received this tool output: [output]. Does this match what you expected? If not, what does it mean for your plan?"

More structured reflection prompts can ask the model to score its own confidence in the current path, identify what assumptions it made that turned out to be wrong, or explicitly list what it still does not know.

This pattern shows up in the AI agent architecture patterns that teams actually ship. Reflection is what separates agents that recover gracefully from unexpected situations and agents that stubbornly repeat the same failing action five times because nothing in the loop told them to reconsider.

The implementation is usually simple: a template in your agent loop that appends a reflection question to the observation before the model sees it. The hard part is knowing when to inject it. Injecting after every step creates noise. Injecting only on explicit failures misses the cases where the step "succeeded" but produced output that points in the wrong direction.

A good heuristic: inject reflection when tool output diverges meaningfully from what the model would have predicted based on its last plan, or when the agent is about to take an irreversible action.

Common mistakes in agent prompting

Treating the system prompt as a chatbot persona. This puts all the attention on how the agent talks and none on how it decides. The result is an agent with a charming personality that makes terrible decisions.

Forgetting that the system prompt repeats. In most agent implementations, the system prompt is included in every call to the model. Instructions that make sense once ("first, read the task description") can cause confusion when the model is on iteration twelve and there is no longer a task description to read. Write system prompts that make sense at any point in the loop, not just at the start.

Writing constraints that are aspirational, not operational. "Be careful with sensitive data" is not a constraint. "Do not write any value from the users table to a file or include it in a tool call output" is a constraint. The first version makes the developer feel better. The second version actually changes behavior.

Leaving tool selection fully implicit. If you have ten tools, the model has to infer from context which one to use in any given situation. Some of that inference will be wrong. Adding even a brief "use this tool when X, prefer Y over Z when both could work" to tool descriptions dramatically reduces misuse.

No stopping condition. An agent without a clear stopping condition will guess when it's done. Sometimes it will guess right. When it guesses wrong in the direction of stopping too late, you get runaway agents that keep working on a task that was already finished. When it guesses wrong in the direction of stopping too early, you get agents that declare success before they have actually done anything useful.

Over-prompting. This is the less-discussed failure mode. Adding constraint after constraint, reflection after reflection, planning step after planning step, until the system prompt is two thousand words long and the model spends most of its reasoning budget just parsing its own instructions. Long system prompts introduce their own errors because models treat instructions later in a long prompt as less important. Keep it dense, not long.

Examples of agent prompting in practice

Here is a concrete before-and-after for a code review agent.

Before:

You are a helpful code reviewer. Review the code the user provides and give feedback. Be thorough and specific. Use the file reading tools as needed.

After:

You are a code review agent for a Python codebase. Your job is to identify bugs, security issues, and violations of the project's style guide. You have access to three tools: read_file, search_codebase, and submit_review.

Start every review by reading the diff provided in the task. If you need to understand context for a function, use search_codebase to find its definition. Do not read files outside the src/ directory.

Submit exactly one review using submit_review when you have checked the full diff. Do not call submit_review more than once. Do not loop after submitting.

Format your review as: [Bug], [Security], or [Style] followed by file name, line number, and a one-sentence description of the issue. If there are no issues, submit a review that says "No issues found."

The second version is longer, but every word does work. The role is specific. The tools have explicit guidance. The stopping condition is unambiguous. The output format prevents the model from making a formatting decision it can get wrong.

Putting it together: the prompt review checklist

Before shipping an agent to any kind of production use, run through these questions on the prompt stack:

• Does the system prompt say what the agent should do, not just what kind of agent it is?
• Does every tool description explain when to use the tool and when not to?
• Is there a clear stopping condition?
• Are the constraints operational (testable, specific) rather than aspirational?
• Does the system prompt still make sense if the model reads it on iteration fifteen, not just iteration one?
• Is there a planning step for tasks that involve more than five sequential decisions?
• Is there a reflection mechanism for handling unexpected tool outputs or failures?
• Is the system prompt shorter than it could be while still covering all the above?

The how do AI agents work post explains the underlying loop that these prompts are meant to govern. Reading that alongside this guide gives you a complete picture of both the mechanics and the instructions that shape them.

Agent prompting is still an immature practice. Most of the knowledge is held informally by people who have shipped agents that broke in production and fixed them. The good news is that the failure modes are consistent. Bad tool descriptions, missing stopping conditions, and constraints that do not constrain - these are the same problems across almost every team. Fix those three things and your agents will behave meaningfully better before you have to think about anything more advanced.