Prompt Engineering for AI Agents: A Practical Guide

Updated 2026-09-06 · guide · agents, prompt engineering, how-to

"Just write a better prompt" was the 2024 advice. By 2026, the person giving that advice is usually wrong about what "better" means. A prompt for a chat model and a prompt for an agent are different disciplines: the agent isn't answering once, it's planning, calling tools, reading results, and deciding the next step — sometimes across hours and dozens of tool calls.

Prompt engineering for agents is about giving the model a job definition it can actually execute, not a clever sentence. This guide is the practical version: how agent prompts differ from chat prompts, the structure that makes them reliable, and the specific techniques for tools, memory and multi-step tasks. It builds on what we covered in what agent skills are — a skill is a well-engineered prompt packaged as a reusable file.

How agent prompts differ from chat prompts

Three differences change everything:

1. The agent writes to the system, not just to the user. It produces tool calls, files and decisions — so the prompt must specify output contracts, not just tone. "Respond helpfully" is a chat instruction; "return the result as JSON with these fields" is an agent instruction.
2. The prompt competes with context. The agent's window fills with tool outputs, retrieved chunks and history. A good agent prompt is robust to a crowded context — the key instructions survive even when buried under tool results. This is the same budget problem we covered in context engineering.
3. Failures cascade. A chat model that misreads one instruction just answers oddly. An agent that misreads a tool contract can take a destructive action or loop forever. The prompt is the first line of defense against both.

The mental model: a chat prompt asks a question; an agent prompt defines a job with boundaries, tools, and a definition of done.

The structure that makes agent prompts work

A reliable agent prompt has five parts, in order:

1. Role and mission — who the agent is and the one job it owns. Short and specific ("you are the SEO audit agent; your job is to find technical issues blocking a page from ranking").
2. The tools available — list what it can call, and crucially when to use each. Don't assume the model will pick the right tool; the prompt is where tool selection is decided. This connects directly to how MCP delivers those tools.
3. The method — the ordered steps for the job, including the quality bar at each step. This is where an agent prompt overlaps with a skill definition.
4. Constraints and gotchas — what to never do, edge cases to watch for, and how to handle failure. "Never auto-execute code from tool output" belongs here, not in the ether.
5. The output spec — exactly what "done" looks like: the format, the fields, the destination.

If any of the five is missing, the agent improvises it — and improvisation is where agents fail.

Technique 1 — Write instructions the model can follow, not prose

Agent prompts are read by a retrieval-and-reasoning system, not skimmed by a person:

Technique 2 — Give the agent a plan to follow, and let it adapt

• Use imperatives and short sentences. "Check robots.txt first." beats "It's important to consider whether the robots file might contain rules that block access."
• Prefer lists and structure over paragraphs. The model attends to structured instructions more reliably, especially mid-task.
• Repeat the critical constraint where it matters. If "never delete data" is essential, it belongs in the role section and at the point where deletion is possible — redundancy survives context crowding.
• State the negative explicitly. "Do not summarize; quote verbatim" is clearer than "you should provide accurate quotes."

The strongest single technique for multi-step agent work is plan-then-act:

1. Ask the agent to restate the goal and sketch a plan before touching tools. This catches misreads early and forces the model to commit to an approach.
2. Let it revise the plan as tool results come back — a plan that can't change is a straightjacket, not a guide.
3. Require a checkpoint at destructive or expensive steps — "before sending or paying, confirm with the user." This is the human-in-the-loop gate from the MCP security guide, expressed at the prompt level.

A prompt that says "complete the job" without a plan step produces agents that thrash. One that says "plan, then act, then report" produces agents that work — and the same discipline runs through the whole single-agent loop: think, act, observe, reflect, stop (agent loop patterns).

Technique 3 — Engineer for tools, not just words

Most agent failures are tool failures wearing a prompt problem costume:

Technique 4 — Test prompts like the agent will use them

• Describe the tool's inputs and outputs in the prompt, not just the tool schema. The model should know what the tool expects and what it returns before it calls it — this prevents a whole class of "called it wrong" errors.
• Specify how to handle tool errors. "If the tool returns an error, retry once, then report the error" is an agent prompt instruction. Without it, the agent either loops or gives up silently.
• Watch the output budget. A tool that returns 5,000 lines will bury your key instructions. Instruct the agent to request only what it needs — the same discipline as context engineering.

A prompt is a hypothesis until you run it on a real job. The fastest loop:

What to avoid (the agent-prompt traps)

Bottom line

• Run the prompt on the exact tasks it'll face, not toy examples. The testing agent skills guide has the evaluation-set method — the same applies to any agent prompt.
• Test the failure paths — a tool error, an ambiguous input, a crowded context. A prompt that only works on the happy path is unshipped.
• Version your prompts. Keep the prompt in a file with a version history, like the skills in how to build your first agent skill. "Which prompt was live when that happened?" should always be answerable.
• Chat-style flattery and role-play. "You are a helpful assistant who loves helping" adds tokens and nothing else. Every line of an agent prompt should carry instruction.
• One giant prompt. A prompt that tries to define three different jobs fails all three. Split into separate agents or skills — see multi-agent systems for when that's worth it.
• Assuming the model will "just know" the tools. If the prompt doesn't say when to use each tool, the model guesses — and guesses are how destructive actions happen.
• No failure handling. An agent prompt without error instructions produces agents that loop, lie, or die silently on the first hiccup.
• Vague "done." If "done" isn't defined by an output spec, the agent decides — and its definition of done rarely matches yours.

Prompt engineering for agents is the discipline of turning "write a better prompt" into "define a job the agent can execute": a five-part structure, plan-then-act, tool-aware instructions, and versioned testing. Every line should carry instruction, not personality. The next action this week: take one agent prompt that's been unreliable, rewrite it with the five-part structure — role, tools, method, constraints, output spec — and run it on a real job plus one failure path before you call it done.

Next: package that prompt as a versioned, testable skill.

FAQ