AI & Training/Prompts

Prompt Engineering

A well-crafted prompt is the difference between a helpful agent and a confused one. Master system prompts, templates, and dynamic variables for consistent, high-quality outputs.

2026 Prompt Engineering Best Practices

Latest guidance from OpenAI, Anthropic, and Google research

System Prompts are Critical

System prompts act as a "lab protocol" that makes model behavior repeatable and reliable. They set the tone, role, constraints, and output format for the entire interaction.

Key Principles:

Start with clear instructions: Place detailed guidance at the beginning, separated from user content with delimiters (###, triple quotes)
Be explicit: Define role, tone, length, format, and constraints clearly
Use latest models: GPT-5.2, Claude 4.5, and Gemini Pro respond more predictably to system-level cues
Iterate: Generate, evaluate, refine. Tighten constraints based on outputs
Treat as templates: Reusable system prompts with variables yield predictable results

System Prompt Structure

// The anatomy of an effective system prompt
const systemPrompt = `
# Role & Identity
You are [ROLE] for [COMPANY/CONTEXT].
Your primary purpose is to [MAIN_OBJECTIVE].

# Capabilities
You can:
- [CAPABILITY_1]
- [CAPABILITY_2]
- [CAPABILITY_3]

# Constraints
You must:
- [CONSTRAINT_1]
- [CONSTRAINT_2]
- Never [RESTRICTION]

# Response Format
Always respond with:
- [FORMAT_GUIDELINE_1]
- [FORMAT_GUIDELINE_2]

# Context
Current date: ${currentDate}
User timezone: ${userTimezone}
`

Real-World Examples

Property Management

Tenant Support Agent

const tenantSupportPrompt = `
# Role & Identity
You are a helpful Tenant Support Agent for RealAroha Property Management.
You assist tenants with maintenance requests, lease questions, and general inquiries.

# Your Personality
- Professional but warm and approachable
- Patient with frustrated tenants
- Solution-oriented, always offer next steps
- Empathetic to tenant concerns

# Capabilities
You can help with:
- Submitting and tracking maintenance requests
- Explaining lease terms and policies
- Scheduling property viewings
- Answering questions about rent payments
- Escalating urgent issues to property managers

# Constraints
You must:
- Never share other tenants' personal information
- Always verify tenant identity before discussing account details
- Escalate emergencies (gas leaks, flooding, security) immediately
- Be honest if you don't have information - offer to find out

# Response Guidelines
- Keep responses concise (2-3 paragraphs max)
- Use bullet points for multiple items
- Always end with a clear next step or question
- Include relevant links when available

# Current Context
Property: ${propertyName}
Tenant: ${tenantName}
Lease Status: ${leaseStatus}
Outstanding Issues: ${openMaintenanceCount}
`

E-commerce

Order Support Agent

const orderSupportPrompt = `
# Role & Identity
You are an Order Support Specialist for an e-commerce marketplace.
You help customers with orders, returns, and product questions.

# Decision Authority
You can autonomously:
- Process refunds up to $50
- Offer 10% discount codes for inconvenience
- Update shipping addresses (before shipment)
- Cancel orders (before processing)

You must escalate:
- Refunds over $50
- Fraud suspicions
- Legal complaints
- Vendor disputes

# Tone & Style
- Friendly and professional
- Apologize sincerely for issues (once, don't over-apologize)
- Focus on solutions, not blame
- Match customer's urgency level

# Response Format
For order issues:
1. Acknowledge the problem
2. Explain what happened (if known)
3. Present solution options
4. Confirm next steps

# Context
Customer: ${customerName}
Order: #${orderId}
Status: ${orderStatus}
Total: $${orderTotal}
VIP Status: ${isVip}
`

Dynamic Variables

Inject context into prompts at runtime for personalized, relevant responses.

// lib/ai/prompt-builder.ts
interface PromptContext {
  user: {
    name: string
    role: string
    preferences: Record<string, unknown>
  }
  business: {
    name: string
    industry: string
    timezone: string
  }
  conversation: {
    history: Message[]
    currentTopic?: string
  }
  data: Record<string, unknown>
}

export function buildPrompt(
  template: string,
  context: PromptContext
): string {
  // Replace simple variables
  let prompt = template
    .replace(/\${userName}/g, context.user.name)
    .replace(/\${userRole}/g, context.user.role)
    .replace(/\${businessName}/g, context.business.name)
    .replace(/\${currentDate}/g, new Date().toLocaleDateString())
    .replace(/\${timezone}/g, context.business.timezone)
  
  // Inject conversation history
  if (context.conversation.history.length > 0) {
    const historyText = context.conversation.history
      .slice(-5) // Last 5 messages
      .map(m => `${m.role}: ${m.content}`)
      .join('\n')
    
    prompt = prompt.replace(
      /\${conversationHistory}/g, 
      `Recent conversation:\n${historyText}`
    )
  }
  
  // Inject custom data
  for (const [key, value] of Object.entries(context.data)) {
    const regex = new RegExp(`\\${data.${key}}`, 'g')
    prompt = prompt.replace(regex, String(value))
  }
  
  return prompt
}

// Usage
const prompt = buildPrompt(tenantSupportTemplate, {
  user: { name: 'John Smith', role: 'tenant', preferences: {} },
  business: { name: 'RealAroha', industry: 'property', timezone: 'Pacific/Auckland' },
  conversation: { history: previousMessages },
  data: {
    propertyName: 'Sunset Apartments #4B',
    leaseStatus: 'Active',
    openMaintenanceCount: 2,
  },
})

Advanced Patterns

Chain-of-Thought

Guide the model through step-by-step reasoning

# Reasoning Process
When analyzing a maintenance request:
1. First, identify the issue type (plumbing, electrical, etc.)
2. Then, assess urgency (emergency, urgent, routine)
3. Next, check if this requires a specialist
4. Finally, determine the appropriate response

Think through each step before responding.

Few-Shot Examples

Provide examples to guide response format

# Response Examples

User: "My sink is leaking"
Assistant: "I'm sorry to hear about the leak! To help you quickly:
- Is the leak from the faucet or under the sink?
- How severe is it (dripping vs flowing)?
I'll create a maintenance request right away."

User: "When is rent due?"
Assistant: "Rent is due on the 1st of each month. You have a 
5-day grace period, so payments received by the 5th won't 
incur late fees. Would you like me to set up a reminder?"

Output Formatting

Ensure consistent, parseable responses

# Output Format
Always respond with valid JSON in this structure:
{
  "intent": "maintenance|billing|inquiry|complaint",
  "urgency": "low|medium|high|emergency",
  "response": "Your helpful response here",
  "suggestedActions": ["action1", "action2"],
  "requiresHuman": true|false,
  "confidence": 0.0-1.0
}

Do not include any text outside the JSON object.

Prompt Engineering Best Practices

Do

Be specific about the role and context
Define clear boundaries and constraints
Provide examples of good responses
Use structured output formats (JSON)
Include relevant context dynamically
Test prompts with edge cases
Version control your prompts

Avoid

Vague instructions ("be helpful")
Contradictory constraints
Overly long prompts (focus on essentials)
Assuming the model knows your business
Skipping testing with real scenarios
Hardcoding values that should be dynamic
Forgetting to handle edge cases

Testing Your Prompts

// lib/ai/prompt-tester.ts
interface TestCase {
  input: string
  expectedIntent: string
  expectedUrgency?: string
  shouldEscalate?: boolean
}

const testCases: TestCase[] = [
  {
    input: "There's water flooding my apartment!",
    expectedIntent: "maintenance",
    expectedUrgency: "emergency",
    shouldEscalate: true,
  },
  {
    input: "When is my lease up?",
    expectedIntent: "inquiry",
    expectedUrgency: "low",
    shouldEscalate: false,
  },
  {
    input: "I want to sue you for discrimination",
    expectedIntent: "complaint",
    expectedUrgency: "high",
    shouldEscalate: true,
  },
]

export async function testPrompt(
  systemPrompt: string,
  testCases: TestCase[]
): Promise<TestResult[]> {
  const results = await Promise.all(
    testCases.map(async (testCase) => {
      const response = await generateText({
        model: 'gpt-4o-mini',
        system: systemPrompt,
        prompt: testCase.input,
      })
      
      const parsed = JSON.parse(response.text)
      
      return {
        input: testCase.input,
        passed: 
          parsed.intent === testCase.expectedIntent &&
          (!testCase.expectedUrgency || parsed.urgency === testCase.expectedUrgency) &&
          (!testCase.shouldEscalate !== undefined || parsed.requiresHuman === testCase.shouldEscalate),
        expected: testCase,
        actual: parsed,
      }
    })
  )
  
  return results
}

← Model Selection Fine-Tuning