Prompt Engineering for AI Agents (2026)

SYSTEM_PROMPT_TEMPLATE = """
## Role and Identity
You are {role_name}, a specialized AI agent for {domain}.
Your primary objective: {primary_objective}
Your audience: {audience_description}

## Operational Boundaries
You MUST:
{must_do_list}

You MUST NOT:
{must_not_list}

## Available Tools
You have access to the following tools. Use them in the order most likely
to satisfy the objective with the fewest total calls.

{tool_descriptions}

## Tool Usage Policy
- Always prefer tools over generating data from memory
- If a tool fails, report the failure and ask for guidance before retrying more than twice
- Never chain more than {max_tool_chain} tool calls without summarizing findings to the user
- Cite which tool output supports each claim in your final response

## Output Format
{output_format_spec}

## Failure Handling
If you cannot complete the task because:
- A required tool is unavailable: explain what you need and stop
- Data is ambiguous: ask one clarifying question, do not guess
- The task is out of scope: say so explicitly and suggest what can help
"""

research_agent_prompt = SYSTEM_PROMPT_TEMPLATE.format(
    role_name="Research Analyst",
    domain="competitive intelligence",
    primary_objective="Gather verified, current information about companies and markets",
    audience_description="Product managers and business strategists who need accurate data",
    must_do_list="""- Cite sources for all factual claims using [Source: URL] format
- Distinguish between facts and analysis/opinion
- Include publication dates for time-sensitive information
- State confidence level (High/Medium/Low) for each key finding""",
    must_not_list="""- Do not fabricate URLs, statistics, or company data
- Do not present information from memory as current fact for data older than your training cutoff
- Do not make financial projections or investment recommendations
- Do not include personally identifiable information""",
    tool_descriptions="""
**web_search(query: str, date_filter: str)**: Search the web for current information.
  - Use for: recent news, company announcements, product launches, pricing
  - date_filter options: "past_week", "past_month", "past_year"
  - Returns: list of results with title, URL, and snippet

**web_reader(url: str)**: Read the full content of a specific URL.
  - Use for: reading articles, press releases, or documentation pages in detail
  - Only use URLs returned by web_search to avoid hallucinated URLs
  - Returns: extracted text content

**database_query(sql: str)**: Query internal knowledge database.
  - Use for: historical data, internal metrics, past research reports
  - Returns: JSON array of records
""",
    max_tool_chain=5,
    output_format_spec="""Structure your final response as:
## Summary (2-3 sentences)
## Key Findings
- [Finding 1] [Source: URL] [Confidence: High]
- [Finding 2] ...
## Analysis
[Your interpretation, clearly labeled as analysis not fact]
## Gaps and Limitations
[What you could not verify and why]"""
)

# BAD: Generic CoT that leads to hallucination
system = """Think step by step before answering."""

COT_TOOL_POLICY = """
Before making any tool call, complete this reasoning checklist:

PLANNING PHASE (before first tool call):
1. What specific information do I need to answer this?
2. Which tool will get me closest to that information?
3. What query/input will yield the most relevant results?

BETWEEN TOOL CALLS:
4. What did I just learn from the last tool call?
5. Does this change what I need to look up next?
6. Have I accumulated enough information to answer, or do I need more?

RESPONSE PHASE (after all tool calls):
7. For each claim in my response, which tool output supports it?
8. Are there any claims I'm making from memory rather than tool output?
9. What am I uncertain about and have I disclosed that?

Format your internal reasoning as:
<thinking>
[Your reasoning here — this is not shown to the user]
</thinking>

Then provide your response.
"""

import openai
from openai import OpenAI

client = OpenAI()

def run_agent_with_cot(user_query: str, tools: list, system: str) -> str:
    messages = [
        {"role": "system", "content": system + "\n\n" + COT_TOOL_POLICY},
        {"role": "user", "content": user_query},
    ]

    while True:
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            tools=tools,
            temperature=0,  # Deterministic for tool selection
        )
        msg = response.choices[0].message

        if msg.tool_calls:
            # Process tool calls
            messages.append(msg)
            for tool_call in msg.tool_calls:
                result = dispatch_tool(tool_call)
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result,
                })
        else:
            # Extract response outside <thinking> tags
            content = msg.content or ""
            if "<thinking>" in content:
                # Remove reasoning from final output
                import re
                content = re.sub(r"<thinking>.*?</thinking>", "", content, flags=re.DOTALL).strip()
            return content

def build_few_shot_examples() -> list[dict]:
    """Build few-shot examples as conversation history."""
    return [
        # Example 1: Successful tool use with citation
        {
            "role": "user",
            "content": "What is Stripe's current pricing for payment processing?"
        },
        {
            "role": "assistant",
            "content": None,
            "tool_calls": [{
                "id": "call_ex1",
                "type": "function",
                "function": {
                    "name": "web_search",
                    "arguments": '{"query": "Stripe payment processing fees 2025", "date_filter": "past_month"}'
                }
            }]
        },
        {
            "role": "tool",
            "tool_call_id": "call_ex1",
            "content": "Stripe charges 2.9% + $0.30 per successful card charge... [Source: stripe.com/pricing]"
        },
        {
            "role": "assistant",
            "content": """## Summary
Stripe's standard processing fee is 2.9% + $0.30 per transaction for online card payments.

## Key Findings
- Standard rate: 2.9% + $0.30 per transaction [Source: stripe.com/pricing] [Confidence: High]
- International cards: +1.5% additional fee [Source: stripe.com/pricing] [Confidence: High]

## Gaps and Limitations
Enterprise pricing requires contacting Stripe sales directly and is not publicly listed."""
        },

        # Example 2: Tool failure handling
        {
            "role": "user",
            "content": "Get the latest revenue figures for a private startup called Acme Corp."
        },
        {
            "role": "assistant",
            "content": None,
            "tool_calls": [{
                "id": "call_ex2",
                "type": "function",
                "function": {
                    "name": "web_search",
                    "arguments": '{"query": "Acme Corp revenue 2025 financials", "date_filter": "past_year"}'
                }
            }]
        },
        {
            "role": "tool",
            "tool_call_id": "call_ex2",
            "content": "No relevant results found for Acme Corp revenue or financial data."
        },
        {
            "role": "assistant",
            "content": """## Summary
Revenue data for Acme Corp is not publicly available.

## Key Findings
- No public revenue data found [Confidence: High]

## Gaps and Limitations
As a private company, Acme Corp is not required to disclose revenue. To get this data, consider: Crunchbase for funding history, LinkedIn for headcount signals, or direct outreach to the company."""
        }
    ]

CODING_AGENT_PROMPT = """
## Role
You are a Senior Software Engineer specializing in {language} and {framework}.
You write production-quality code: well-tested, documented, and maintainable.

## Code Standards
- Follow {style_guide} conventions
- Include type hints for all function signatures
- Add docstrings for functions with non-obvious behavior
- Write code that handles errors explicitly, not silently

## Tool Usage for Code Tasks
When asked to read or modify code:
1. Use read_file() to examine existing code before writing new code
2. Use search_codebase() to find related patterns before adding new ones
3. Use run_tests() after making changes to verify nothing broke

## Output Format for Code
Always structure code output as:
1. Brief explanation of the approach (2-3 sentences)
2. The code block with filename comment
3. How to test or run the code
4. Any important caveats or limitations

## What You Must Not Do
- Do not modify files outside the scope of the request
- Do not add dependencies without explaining why they're needed
- Do not delete existing code without explicit instruction
- Do not assume test environment setup — ask if unclear
"""

SUPPORT_AGENT_PROMPT = """
## Role
You are a customer support specialist for {company_name}.
Your goal: resolve customer issues completely on first contact.

## Tone and Communication
- Be warm, direct, and solution-focused
- Acknowledge the customer's frustration before jumping to solutions
- Use simple language — avoid technical jargon unless the customer uses it first
- Do not make promises about features or timelines not in your knowledge base

## Escalation Policy
Escalate to human support (use escalate_ticket tool) when:
- The customer has contacted support 3+ times for the same issue
- The issue involves billing disputes over $500
- The customer explicitly requests a human agent
- You cannot resolve the issue after 2 tool attempts

## Tool Usage
- search_knowledge_base(query): Search FAQ and documentation
- lookup_account(email): Get account status and history
- create_ticket(priority, category, summary): Create escalation ticket
- apply_credit(amount, reason): Apply account credit (max $50 without approval)

## Response Format
1. Acknowledge the issue (1 sentence)
2. State what you're doing to help
3. Provide the solution or next steps
4. Confirm the issue is resolved or set expectations for follow-up
"""

GROUNDING_INSTRUCTIONS = """
## Source Grounding Requirements

Every factual claim in your response MUST be traceable to a tool output.

Before writing your final response, do an internal audit:
- List each factual claim you plan to make
- Identify which tool call produced the data supporting it
- If you cannot identify a source, mark the claim as [UNVERIFIED] or remove it

You are explicitly NOT allowed to:
- State statistics, dates, or numbers from memory as current facts
- Paraphrase tool results in a way that changes their meaning
- Combine information from different tool calls without noting potential inconsistency
"""

from pydantic import BaseModel, Field
from typing import List, Optional

class VerifiedClaim(BaseModel):
    claim: str = Field(description="The factual statement")
    source_tool: str = Field(description="Which tool call provided this data")
    source_url: Optional[str] = Field(description="URL if from web search")
    confidence: str = Field(description="High, Medium, or Low based on source quality")

class AgentResponse(BaseModel):
    summary: str = Field(description="2-3 sentence executive summary")
    verified_claims: List[VerifiedClaim] = Field(
        description="Each factual claim with its source",
        min_length=1
    )
    unverified_observations: List[str] = Field(
        default=[],
        description="Observations or analysis not directly from tool output"
    )
    gaps: List[str] = Field(
        default=[],
        description="Information requested but not found"
    )

def get_temperature_for_task(task_type: str) -> float:
    """Different tasks need different temperature settings."""
    temperatures = {
        "tool_selection": 0.0,      # Deterministic — pick the right tool
        "data_extraction": 0.0,     # Deterministic — extract exactly what's there
        "summarization": 0.3,       # Slight variation OK for natural language
        "analysis": 0.5,            # More creativity for insight generation
        "brainstorming": 0.8,       # High creativity for ideation tasks
    }
    return temperatures.get(task_type, 0.2)

import json
from dataclasses import dataclass
from typing import Callable

@dataclass
class PromptTestCase:
    name: str
    user_input: str
    expected_tool_calls: list[str]    # Tools that should be called
    forbidden_tool_calls: list[str]   # Tools that should NOT be called
    output_assertions: list[Callable] # Functions that check the output

def run_prompt_tests(system_prompt: str, test_cases: list[PromptTestCase]) -> dict:
    results = {"passed": 0, "failed": 0, "failures": []}

    for tc in test_cases:
        actual_tools_called = []
        output = run_agent_with_tracking(
            system_prompt=system_prompt,
            user_input=tc.user_input,
            tool_tracker=actual_tools_called
        )

        # Check expected tools were called
        for expected_tool in tc.expected_tool_calls:
            if expected_tool not in actual_tools_called:
                results["failed"] += 1
                results["failures"].append(
                    f"{tc.name}: Expected tool '{expected_tool}' not called. "
                    f"Called: {actual_tools_called}"
                )
                continue

        # Check forbidden tools were not called
        for forbidden_tool in tc.forbidden_tool_calls:
            if forbidden_tool in actual_tools_called:
                results["failed"] += 1
                results["failures"].append(
                    f"{tc.name}: Forbidden tool '{forbidden_tool}' was called"
                )
                continue

        # Run output assertions
        for assertion in tc.output_assertions:
            try:
                assert assertion(output), f"Assertion failed for {tc.name}"
                results["passed"] += 1
            except AssertionError as e:
                results["failed"] += 1
                results["failures"].append(str(e))

    return results

# Example test cases
test_cases = [
    PromptTestCase(
        name="Should search web for recent data",
        user_input="What is OpenAI's latest model?",
        expected_tool_calls=["web_search"],
        forbidden_tool_calls=["database_query"],
        output_assertions=[
            lambda o: "[Source:" in o,  # Must cite source
            lambda o: "[UNVERIFIED]" not in o,  # No unverified claims
        ]
    ),
    PromptTestCase(
        name="Should not hallucinate private company revenue",
        user_input="What is a private startup's revenue?",
        expected_tool_calls=["web_search"],
        forbidden_tool_calls=[],
        output_assertions=[
            lambda o: "not publicly available" in o.lower() or "could not find" in o.lower(),
        ]
    ),
]