Prompt Engineering for AI Agents

Why Agent Prompts Are Different

In single-turn prompting, you control the input and receive one output. If the output is wrong, you adjust the prompt and try again. The prompt only needs to handle one specific task, and you can iterate until it works. The feedback loop is tight: prompt, output, evaluate, revise.

Agent prompts face a different challenge. The model executes multiple steps autonomously, and errors compound. A slightly wrong tool choice in step 2 produces incorrect data that pollutes the reasoning in steps 3 through 8. By the time the agent produces a final answer, the root cause of the error is buried many turns back. You cannot iterate on individual turns the way you do with single-turn prompts, so the system prompt must be comprehensive enough to prevent errors before they happen.

Agent prompts also face the context window problem. As an agent takes more steps, the conversation history grows. Tool results, reasoning traces, and intermediate outputs consume tokens. A 200,000-token context window sounds enormous, but an agent that makes 15 tool calls with verbose results can fill it surprisingly fast. The system prompt needs to instruct the model on how to be concise, what to retain, and what to summarize as the conversation grows.

The consequence is that agent system prompts are typically much longer and more detailed than single-turn prompts. A good classification prompt might be 200 tokens. A good agent system prompt is often 2,000 to 5,000 tokens, covering identity, capabilities, tool usage rules, error handling, output formatting, behavioral boundaries, and escalation procedures.

The Core Components of an Agent System Prompt

Identity and role establishes what the agent is and how it should present itself. "You are a research assistant that helps users find and synthesize information from multiple sources" is more effective than "You are a helpful AI." The specific role frames every subsequent decision the agent makes. A research assistant prioritizes thoroughness and citation. A customer support agent prioritizes resolution speed and empathy. The role description is the lens through which the model interprets every user request.

Capabilities and limitations tells the agent what it can and cannot do. List the available tools explicitly and describe what each one does. Equally important, state what the agent cannot do: "You cannot access the user's filesystem," "You cannot make purchases on behalf of the user," "You cannot modify production databases." Explicit limitations prevent the agent from attempting impossible actions or making dangerous assumptions about its permissions.

Behavioral rules govern how the agent operates across turns. These include: always reason before acting, verify results before presenting them, ask for clarification when the task is ambiguous, prefer reversible actions over irreversible ones, and report errors honestly rather than hiding them. These rules prevent the most common agent failure modes.

Output formatting ensures the agent's responses are consistent and parseable. If the agent is part of a larger system (feeding results to another model or a UI), the output format must be predictable. Specify whether the agent should use markdown, JSON, plain text, or a custom format, and provide examples of correctly formatted outputs.

Writing Effective Tool Descriptions

Tool descriptions are the most underrated component of agent prompting. The model decides which tool to call based entirely on the tool name, description, and parameter schema. Poor descriptions lead to wrong tool choices, which cascade into failed agent runs.

Each tool description should answer four questions: what does this tool do, when should the agent use it, what input does it need, and what output does it return. Compare these two descriptions for the same tool:

The detailed description prevents three common failures: the agent using the wrong search tool (it knows this only searches internal docs), the agent writing vague queries (it knows to include product names), and the agent misinterpreting empty results (it knows empty means "not found," not "error").

When an agent has access to many tools (10 or more), grouping them by category in the system prompt helps the model navigate. "For data retrieval, use search_kb or query_database. For actions, use create_ticket, update_record, or send_notification. For analysis, use calculate or compare_options." This mental model helps the agent select tools more efficiently, similar to how organizing a workbench helps a human find the right tool faster.

Multi-Turn Context Management

Agents accumulate context with every step. The system prompt, tool results, reasoning traces, and user messages all compete for space in the context window. Without explicit management instructions, agents tend to carry too much context, eventually hitting the window limit or degrading in quality as the model struggles to attend to relevant information buried in noise.

Instruct the agent on what to retain and what to discard. "After completing a subtask, summarize the result in one sentence and use that summary in future reasoning rather than referencing the full tool output." This keeps the working context clean without losing important information.

For long-running agents, instruct the model to periodically assess progress. "After every 5 steps, review what you have accomplished, what remains, and whether your approach is still the most efficient path." This prevents the agent from going down rabbit holes and helps it self-correct when an early decision was wrong.

Memory systems like Adaptive Recall address context management at the infrastructure level. Rather than carrying all context in the conversation window, the agent stores important findings in persistent memory and retrieves them when needed. This allows agents to operate across sessions and scale to tasks that would exceed any context window.

Error Recovery Instructions

Agents encounter errors: API calls fail, tools return unexpected results, searches find nothing, and calculations produce impossible numbers. Without explicit error recovery instructions, models handle errors inconsistently. Some retry indefinitely, some give up immediately, some hallucinate a plausible result and continue as if nothing went wrong.

Write explicit error handling rules into the system prompt:

The last rule is critical. The most dangerous agent failure mode is silent error swallowing, where the agent encounters a problem, ignores it, and continues with incomplete information. The user receives a confident-sounding result that is based on missing data, with no indication that anything went wrong. Explicit instructions to acknowledge failures make this behavior much less likely.

Behavioral Boundaries and Safety

Agent autonomy creates risks that do not exist in single-turn prompting. A model that can take actions (write files, send emails, execute code, modify databases) can cause real-world consequences that are difficult to reverse. The system prompt must define clear boundaries.

Action classification separates safe actions from dangerous ones. Reading data is safe. Creating a draft document is safe. Sending an email to a customer is dangerous, it cannot be unsent. Deleting records is dangerous. Modifying production configuration is very dangerous. The system prompt should categorize actions and require different levels of caution for each category.

Confirmation requirements specify which actions the agent can take autonomously and which require user approval. "You may search, read files, and create drafts without asking. Before sending any external communication, modifying any database record, or executing any irreversible action, present your plan and wait for user confirmation." This gives the agent freedom on safe operations while preventing irreversible mistakes.

Scope constraints prevent the agent from expanding beyond its intended domain. Without scope constraints, agents sometimes interpret broad user requests as permission to take sweeping actions. "The user asked me to improve the website, so I will redesign the entire architecture" is a scope expansion that no user intended. Instruct the agent to "complete the specific task requested without expanding scope" and to "ask for confirmation before taking any action that goes beyond the original request."

The AI guardrails guide covers safety patterns for agents in depth, including input validation, output filtering, and rate limiting for autonomous tool calls.

Prompting for Planning

Complex tasks require the agent to plan before acting. Without planning instructions, agents tend to start executing immediately, making decisions as they go. This works for simple tasks but fails on complex ones where the order of operations matters, where some subtasks depend on others, and where the overall strategy should be evaluated before committing to it.

Add explicit planning instructions to the system prompt: "For tasks with more than 3 steps, first create a plan listing all steps before executing any of them. Present the plan to the user for review. Then execute steps sequentially, marking each as complete." This produces more reliable results because planning failures are caught before they cause cascading execution failures.

Planning also improves transparency. When the agent shows its plan, the user can spot problems early, redirect the approach, or provide additional context that changes the strategy. This collaborative planning pattern is particularly important for agents working on codebases, where a wrong architectural decision in the planning phase prevents wasted implementation effort.

Testing Agent Prompts

Agent prompts are harder to test than single-turn prompts because the same initial prompt can produce different execution paths on different runs. Temperature, tool result variability, and the model's stochastic nature mean that two runs of the same agent on the same task might take different paths to the same answer, or might arrive at different answers entirely.

Test agent prompts with a suite of scenarios that cover: straightforward tasks the agent should complete easily, edge cases where the correct behavior is ambiguous, error scenarios where tools fail or return unexpected results, and adversarial inputs where the user tries to make the agent exceed its boundaries. For each scenario, define not just the expected final answer but the expected behavioral pattern: did the agent plan before acting, did it handle errors correctly, did it stay within scope, did it ask for confirmation before dangerous actions.

Log complete agent traces (all thoughts, actions, and observations) during testing. When an agent fails, the trace tells you where the failure originated, which is usually many steps before the wrong final answer appeared. Without traces, debugging agent behavior is nearly impossible because you only see the symptom (wrong answer) without the cause (wrong tool choice in step 3). The prompt testing guide covers systematic evaluation approaches that work for multi-turn agent interactions.

Common Patterns That Work

The cautious agent pattern instructs the model to prefer asking for clarification over making assumptions. "When the user's request is ambiguous, ask a specific clarifying question rather than guessing." This produces slower but more accurate agents that rarely take wrong actions based on misunderstood instructions.

The checkpoint pattern instructs the model to report progress at defined intervals. "After completing each major step, summarize what you did, what you found, and what you plan to do next." This keeps the user informed and creates natural points where the user can redirect the agent.

The minimal action pattern instructs the model to prefer the least powerful tool that accomplishes the task. "If you can answer from your existing knowledge, do not search. If a read-only query provides the answer, do not use a write operation." This reduces side effects and makes agent runs more predictable.