====== Prompt Engineering ======

Prompt engineering for AI agents is the discipline of designing system prompts, instructions, and interaction patterns that reliably guide agent behavior across complex, multi-step tasks. Unlike simple chatbot prompting, agent prompt engineering must handle tool calling, memory management, error recovery, and recursive reasoning loops while maintaining consistent behavior across thousands of interactions.

===== System Prompts =====

System prompts define the agent's identity, constraints, and operational rules. In agentic systems, they serve as the foundational behavioral contract:

<code python>
AGENT_SYSTEM_PROMPT = """You are a research assistant agent with access to search and file tools.

## Behavioral Rules
- Always verify claims against retrieved sources before responding
- When uncertain, search for additional information rather than guessing
- Never execute destructive operations without explicit user confirmation
- If a task exceeds your capabilities, explain what you cannot do and suggest alternatives

## Operating Modes
- PLAN MODE: Gather context, ask clarifying questions, outline strategy
- ACT MODE: Execute step-by-step, verify each step before proceeding

## Tool Usage
- Use search_web for current information beyond your training data
- Use read_file for local document analysis
- Use write_file only after user confirms the proposed content

## Output Format
- Cite sources with inline links
- Use structured formatting for complex responses
- Keep responses concise unless detailed analysis is requested
"""
</code>

Effective system prompts in 2025-2026 differentiate between **PLAN MODE** (gathering context, clarifying, strategizing) and **ACT MODE** (step-by-step execution), reducing errors in task completion.

===== Few-Shot Prompting =====

Few-shot prompting provides 1-5 examples in the prompt to guide output format and behavior without fine-tuning. For agents, examples should demonstrate tool calls, error recovery, and multi-step reasoning:

<code python>
FEW_SHOT_EXAMPLES = [
    {
        "user": "Find the population of Tokyo",
        "assistant": "I'll search for the current population of Tokyo.
"
                     "Action: search_web(query='Tokyo population 2026')
"
                     "Observation: Tokyo metro area population is approximately 37.4 million.
"
                     "The population of the Tokyo metropolitan area is approximately 37.4 million."
    },
    {
        "user": "What's 2+2?",
        "assistant": "2 + 2 = 4.

"
                     "Note: I answered directly because this doesn't require tool use."
    }
]
</code>

===== Chain-of-Thought Prompting =====

Chain-of-thought (CoT) prompting instructs agents to reason step-by-step before acting, improving performance on complex tasks by 20-70%. In agent systems, CoT scaffolds the reasoning loop:

  * **Zero-shot CoT** — Simply adding "Let's think step by step" to the prompt
  * **Structured CoT** — Defining explicit reasoning stages (observe, analyze, plan, act)
  * **Tree of Thought** — Exploring multiple reasoning paths and evaluating which is most promising

===== ReAct Prompting =====

ReAct (Reason + Act) is the dominant prompting pattern for tool-using agents, alternating between reasoning and action:

  * **Thought** — The agent reasons about the current state and what to do next
  * **Action** — The agent calls a tool or takes an action
  * **Observation** — The result of the action is fed back to the agent

This loop minimizes hallucinations by grounding reasoning in external feedback at each step.

===== Prompt Templates =====

Templates standardize agent prompts with placeholders for dynamic content, enabling reuse across agents and models:

<code python>
AGENT_TEMPLATE = """
{system_prompt}

## Current Context
User ID: {user_id}
Session: {session_id}
Available Tools: {tool_descriptions}
Memory Context: {relevant_memories}

## Conversation History
{conversation_history}

## Current Task
{user_message}
"""

def build_prompt(user_message, context):
    return AGENT_TEMPLATE.format(
        system_prompt=AGENT_SYSTEM_PROMPT,
        user_id=context.user_id,
        session_id=context.session_id,
        tool_descriptions=format_tools(context.tools),
        relevant_memories=context.memory_search(user_message),
        conversation_history=context.recent_messages(limit=10),
        user_message=user_message
    )
</code>

===== Anti-Patterns =====

| **Anti-Pattern** | **Problem** | **Fix** |
| Generic role prompts | "Act as an expert" yields inconsistent results on modern models | Use precise behavioral instructions tied to tools and workflows |
| Overly long prompts | Bloats tokens, increases cost and latency without proportional gains | Keep prompts focused; move reference data to retrieval |
| Threats and urgency | "This is critical, you must not fail" adds noise, not reliability | Remove emotional language; use structured constraints |
| No evaluation loop | Prompt quality degrades without systematic testing | A/B test prompts with quantitative metrics |
| Static prompts | Fail on noisy real-world inputs; miss memory and tool handling | Use templates with dynamic context injection |
| Ignoring sensitivity | Minor syntax changes can cause 76-point accuracy swings | Always test prompt variations systematically |

===== References =====

  * [[https://www.promptingguide.ai/agents/introduction|Prompting Guide - Agents Introduction]]
  * [[https://www.prompthub.us/blog/prompt-engineering-for-ai-agents|PromptHub - Prompt Engineering for AI Agents]]
  * [[https://www.getmaxim.ai/articles/advanced-prompt-engineering-techniques-in-2025/|Maxim AI - Advanced Prompt Engineering 2025]]

===== See Also =====

  * [[function_calling]] — Tool calling that prompts must orchestrate
  * [[agent_frameworks]] — Frameworks that implement prompt patterns
  * [[agent_safety]] — Defensive prompting against injection attacks
  * [[retrieval_augmented_generation]] — RAG prompts for grounding responses