Prompt Templates Customization Guide

const apiOptimizedTemplate = `<task>
Generate a structured response for {{agentName}} to API request.
</task>

<providers>
{{providers}}
</providers>

<requestContext>
- Platform: REST API
- Endpoint: {{endpoint}}
- Method: {{method}}
- User Agent: {{userAgent}}
</requestContext>

<instructions>
As {{agentName}}, provide a structured response for the API request.

API Response Guidelines:
- Be concise but complete
- Include relevant data points
- Use consistent formatting
- Provide actionable information
- Reference request context when relevant

Response Structure:
- Clear acknowledgment
- Relevant information
- Next steps if applicable
- Error handling if needed
</instructions>

<output>
<response>
    <thought>API request analysis and response strategy</thought>
    <actions>REPLY</actions>
    <providers>KNOWLEDGE,FACTS</providers>
    <text>Structured response for API consumer</text>
    <metadata>
        <responseType>api_response</responseType>
        <confidence>{{confidence}}</confidence>
        <sources>{{sources}}</sources>
    </metadata>
</response>
</output>`;

const discordOptimizedTemplate = `<task>
Generate a Discord message response for {{agentName}}.
</task>

<providers>
{{providers}}
</providers>

<discordContext>
- Server: {{serverName}}
- Channel: {{channelName}}
- Message Type: {{messageType}}
- Mentions: {{mentions}}
- Thread: {{threadInfo}}
</discordContext>

<instructions>
As {{agentName}}, engage with the Discord community.

Discord Guidelines:
- Use Discord markdown (**, *, \`\`\`, etc.)
- Reference users with @mentions when appropriate
- Keep responses conversational and community-focused
- Use emojis sparingly and appropriately
- Consider server context and channel purpose

Response Style:
- Friendly and approachable
- Community-oriented
- Contextually aware
- Engaging and interactive
</instructions>

<output>
<response>
    <thought>Discord community engagement strategy</thought>
    <actions>REPLY</actions>
    <providers>KNOWLEDGE,ENTITIES</providers>
    <text>Discord-formatted response with markdown</text>
    <reactions>👍,✨,🤖</reactions>
</response>
</output>`;

const twitterOptimizedTemplate = `<task>
Generate a Twitter response for {{agentName}}.
</task>

<providers>
{{providers}}
</providers>

<twitterContext>
- Tweet Type: {{tweetType}}
- In Reply To: {{inReplyTo}}
- Mentions: {{mentions}}
- Hashtags: {{hashtags}}
- Character Limit: 280
</twitterContext>

<instructions>
As {{agentName}}, create a Twitter-appropriate response.

Twitter Guidelines:
- Maximum 280 characters
- Use relevant hashtags (#)
- Include @mentions when replying
- Be concise but engaging
- Consider viral potential
- Use Twitter-friendly formatting

Tone Considerations:
- Conversational and accessible
- Personality-driven
- Topical and timely
- Engaging and shareable
</instructions>

<output>
<response>
    <thought>Twitter engagement strategy</thought>
    <actions>REPLY</actions>
    <providers>KNOWLEDGE</providers>
    <text>Concise Twitter response under 280 characters</text>
    <hashtags>#relevant #hashtags</hashtags>
    <mentions>@relevantUsers</mentions>
</response>
</output>`;

export const booleanFooter = 'Respond with only a YES or a NO.';

import { composePromptFromState } from '@elizaos/core';

// Basic usage
const prompt = composePromptFromState({
  state,
  template: messageHandlerTemplate,
});

// The function replaces template variables with state values:
// {{agentName}} -> state.values.agentName
// {{providers}} -> state.text (formatted provider data)
// {{recentMessages}} -> state.values.recentMessages
// {{actionNames}} -> state.values.actionNames
// {{topic}} -> state.values.topic
// {{adjective}} -> state.values.adjective
// And any other values in state.values

// character.json
{
  "name": "TechSupport",
  "bio": ["I'm a technical support specialist helping users with software and hardware issues"],
  "templates": {
    "shouldRespondTemplate": "<custom should respond template>",
    "messageHandlerTemplate": "<custom message handler template>",
    "postCreationTemplate": "<custom post creation template>"
  }
}

{
  "name": "TechSupport",
  "bio": ["I'm a technical support specialist helping users with software and hardware issues"],
  "templates": {
    "messageHandlerTemplate": "<task>\nProvide technical support as {{agentName}}.\n</task>
    
    <providers>
    {{providers}}
    </providers>
    
    <supportContext>
    {{recentMessages}}
    </supportContext>
    
    <instructions>
    As {{agentName}}, provide technical support following these steps:
    
    1. ACKNOWLEDGE the user's issue
    2. ANALYZE the problem description
    3. ASK clarifying questions if needed
    4. PROVIDE step-by-step solution
    5. OFFER follow-up assistance
    
    Technical Support Guidelines:
    - Be patient and understanding
    - Use clear, non-technical language
    - Provide specific, actionable steps
    - Offer multiple solutions when possible
    - Escalate complex issues appropriately
    
    Response Structure:
    - Problem acknowledgment
    - Diagnosis or clarification
    - Solution steps
    - Verification request
    </instructions>
    
    <output>
    <response>
        <thought>Technical analysis and support strategy</thought>
        <actions>REPLY</actions>
        <providers>KNOWLEDGE,FACTS</providers>
        <text>Technical support response with clear steps</text>
        <troubleshooting>
            <diagnosis>Problem analysis</diagnosis>
            <steps>Solution steps</steps>
            <verification>How to verify fix</verification>
        </troubleshooting>
    </response>
    </output>`
  }
}

// In your character definition file
export const myCharacter = {
  name: "MyAgent",
  bio: ["I am a specialized agent"],
  templates: {
    // Override the message handler template
    messageHandlerTemplate: `<task>Generate specialized response for {{agentName}}.</task>

<providers>
{{providers}}
</providers>

<instructions>
Specialized instructions for my agent...
</instructions>

<output>
<response>
    <thought>{{agentName}}'s analysis</thought>
    <actions>REPLY</actions>
    <providers>KNOWLEDGE</providers>
    <text>Specialized response</text>
</response>
</output>`,
    
    // Override should respond template
    shouldRespondTemplate: `<task>Custom decision logic for {{agentName}}</task>
<!-- Custom template content -->`,
    
    // Override post creation template  
    postCreationTemplate: `<task>Create specialized content for {{agentName}}</task>
<!-- Custom template content -->`
  }
};

{
  "name": "SalesBot",
  "bio": ["I'm a sales assistant helping customers find the right products"],
  "templates": {
    "messageHandlerTemplate": "<task>\nProvide sales assistance as {{agentName}}.\n</task>
    
    <providers>
    {{providers}}
    </providers>
    
    <salesContext>
    - Customer: {{customerName}}
    - Previous Interactions: {{recentMessages}}
    - Current Products: {{availableProducts}}
    - Customer Preferences: {{customerPreferences}}
    </salesContext>
    
    <instructions>
    As {{agentName}}, guide customers through the sales process:
    
    SALES METHODOLOGY:
    1. DISCOVER customer needs
    2. PRESENT relevant solutions
    3. HANDLE objections professionally
    4. CLOSE with clear next steps
    
    Sales Guidelines:
    - Be helpful, not pushy
    - Focus on customer value
    - Provide detailed product information
    - Offer comparisons when helpful
    - Create urgency appropriately
    
    Response Style:
    - Professional and friendly
    - Solution-oriented
    - Value-focused
    - Consultative approach
    </instructions>
    
    <output>
    <response>
        <thought>Sales strategy and customer needs analysis</thought>
        <actions>REPLY</actions>
        <providers>KNOWLEDGE,PRODUCTS</providers>
        <text>Sales-focused response with product recommendations</text>
        <products>
            <recommended>Product recommendations</recommended>
            <alternatives>Alternative options</alternatives>
        </products>
        <nextSteps>Clear next steps for customer</nextSteps>
    </response>
    </output>"
  }
}

// In an action or provider
const template = runtime.character.templates?.messageHandlerTemplate 
  || messageHandlerTemplate; // fallback to default

const prompt = composePromptFromState({
  state,
  template
});

{
  "name": "CreativeWriter",
  "bio": ["I'm a creative writing assistant helping with stories, poems, and creative content"],
  "templates": {
    "messageHandlerTemplate": `<task>
    Provide creative writing assistance as {{agentName}}.
    </task>
    
    <providers>
    {{providers}}
    </providers>
    
    <creativeContext>
    - Writing Project: {{projectType}}
    - Genre: {{genre}}
    - Style: {{writingStyle}}
    - Audience: {{targetAudience}}
    - Previous Work: {{recentMessages}}
    </creativeContext>
    
    <instructions>
    As {{agentName}}, help with creative writing by:
    
    CREATIVE PROCESS:
    1. UNDERSTAND the creative vision
    2. BRAINSTORM ideas and concepts
    3. DEVELOP characters, plot, or themes
    4. REFINE and polish content
    5. PROVIDE constructive feedback
    
    Creative Guidelines:
    - Encourage experimentation
    - Provide specific, actionable feedback
    - Offer multiple creative options
    - Balance creativity with structure
    - Inspire and motivate
    
    Response Approach:
    - Enthusiastic and supportive
    - Detail-oriented
    - Imaginative and inspiring
    - Technically skilled
    </instructions>
    
    <output>
    <response>
        <thought>Creative analysis and writing strategy</thought>
        <actions>REPLY</actions>
        <providers>KNOWLEDGE,CREATIVE</providers>
        <text>Creative writing guidance and suggestions</text>
        <techniques>
            <suggested>Writing techniques to try</suggested>
            <examples>Specific examples or prompts</examples>
        </techniques>
        <inspiration>Creative inspiration or direction</inspiration>
    </response>
    </output>`
  }
}

export function selectTemplateForContext(
  message: Memory,
  runtime: IAgentRuntime
): string {
  const messageText = message.content.text?.toLowerCase() || '';
  const source = message.content.source;
  
  // Platform-specific templates
  if (source === 'discord') {
    return runtime.character.templates?.discordTemplate || discordOptimizedTemplate;
  }
  
  if (source === 'twitter') {
    return runtime.character.templates?.twitterTemplate || twitterOptimizedTemplate;
  }
  
  if (source === 'api' || source === 'rest_api') {
    return runtime.character.templates?.apiTemplate || apiOptimizedTemplate;
  }
  
  // Content-specific templates
  if (messageText.includes('support') || messageText.includes('help')) {
    return runtime.character.templates?.supportTemplate || supportHandlerTemplate;
  }
  
  if (messageText.includes('buy') || messageText.includes('price')) {
    return runtime.character.templates?.salesTemplate || salesHandlerTemplate;
  }
  
  if (messageText.includes('write') || messageText.includes('story')) {
    return runtime.character.templates?.creativeTemplate || creativeHandlerTemplate;
  }
  
  // Default template
  return runtime.character.templates?.messageHandlerTemplate || messageHandlerTemplate;
}

export function createInheritedTemplate(
  baseTemplate: string,
  customizations: Record<string, string>
): string {
  let template = baseTemplate;
  
  // Replace specific sections
  Object.entries(customizations).forEach(([section, replacement]) => {
    const sectionRegex = new RegExp(`<${section}>[\\s\\S]*?</${section}>`, 'g');
    template = template.replace(sectionRegex, `<${section}>\n${replacement}\n</${section}>`);
  });
  
  return template;
}

// Usage
const customSupportTemplate = createInheritedTemplate(messageHandlerTemplate, {
  instructions: `
    As a technical support agent:
    1. Acknowledge the technical issue
    2. Gather diagnostic information
    3. Provide step-by-step troubleshooting
    4. Verify the solution works
    5. Document the resolution
  `
});

export function injectContextVariables(
  template: string,
  context: {
    message: Memory;
    runtime: IAgentRuntime;
    additionalContext?: Record<string, any>;
  }
): string {
  const variables = {
    // Standard variables
    agentName: context.runtime.character.name,
    bio: context.runtime.character.bio?.join(' ') || '',
    
    // Context-specific variables
    platform: context.message.content.source || 'unknown',
    userAgent: context.message.content.metadata?.userAgent || 'unknown',
    timestamp: new Date().toISOString(),
    
    // Message context
    hasAttachments: context.message.content.attachments?.length > 0,
    mentionsAgent: context.message.content.text?.includes(context.runtime.character.name),
    
    // Additional context
    ...context.additionalContext
  };
  
  return Object.entries(variables).reduce(
    (template, [key, value]) => 
      template.replace(new RegExp(`{{${key}}}`, 'g'), String(value)),
    template
  );
}

export function validateTemplate(template: string): {
  isValid: boolean;
  errors: string[];
  warnings: string[];
} {
  const errors: string[] = [];
  const warnings: string[] = [];
  
  // Check for required sections
  const requiredSections = ['task', 'instructions', 'output'];
  requiredSections.forEach(section => {
    if (!template.includes(`<${section}>`)) {
      errors.push(`Missing required section: ${section}`);
    }
  });
  
  // Check for output structure
  if (!template.includes('<response>')) {
    errors.push('Missing response structure in output section');
  }
  
  // Check for unclosed tags
  const tagRegex = /<(\w+)>/g;
  const closingTagRegex = /<\/(\w+)>/g;
  
  const openTags = [...template.matchAll(tagRegex)].map(match => match[1]);
  const closeTags = [...template.matchAll(closingTagRegex)].map(match => match[1]);
  
  openTags.forEach(tag => {
    if (!closeTags.includes(tag)) {
      errors.push(`Unclosed tag: ${tag}`);
    }
  });
  
  // Check for common variables
  const commonVars = ['{{agentName}}', '{{providers}}'];
  commonVars.forEach(variable => {
    if (!template.includes(variable)) {
      warnings.push(`Consider including ${variable} for better context`);
    }
  });
  
  return {
    isValid: errors.length === 0,
    errors,
    warnings
  };
}

export class TemplateTestFramework {
  private runtime: IAgentRuntime;
  
  constructor(runtime: IAgentRuntime) {
    this.runtime = runtime;
  }
  
  async testTemplate(
    template: string,
    testCases: Array<{
      input: string;
      expectedActions?: string[];
      expectedKeywords?: string[];
      platform?: string;
    }>
  ): Promise<Array<{
    input: string;
    output: any;
    passed: boolean;
    errors: string[];
  }>> {
    const results = [];
    
    for (const testCase of testCases) {
      try {
        const message = this.createTestMessage(testCase.input, testCase.platform);
        const state = await this.runtime.composeState(message);
        
        // Apply template
        const prompt = this.applyTemplate(template, state);
        
        // Get response
        const response = await this.runtime.useModel(ModelType.TEXT_LARGE, {
          prompt
        });
        
        const parsed = parseKeyValueXml(response);
        const errors = this.validateResponse(parsed, testCase);
        
        results.push({
          input: testCase.input,
          output: parsed,
          passed: errors.length === 0,
          errors
        });
        
      } catch (error) {
        results.push({
          input: testCase.input,
          output: null,
          passed: false,
          errors: [error.message]
        });
      }
    }
    
    return results;
  }
  
  private validateResponse(response: any, testCase: any): string[] {
    const errors: string[] = [];
    
    if (testCase.expectedActions) {
      const actions = response.actions || [];
      testCase.expectedActions.forEach(expectedAction => {
        if (!actions.includes(expectedAction)) {
          errors.push(`Expected action ${expectedAction} not found`);
        }
      });
    }
    
    if (testCase.expectedKeywords) {
      const text = response.text || '';
      testCase.expectedKeywords.forEach(keyword => {
        if (!text.toLowerCase().includes(keyword.toLowerCase())) {
          errors.push(`Expected keyword '${keyword}' not found in response`);
        }
      });
    }
    
    return errors;
  }
}

class TemplateCache {
  private cache = new Map<string, string>();
  private compiled = new Map<string, Function>();
  
  get(key: string): string | undefined {
    return this.cache.get(key);
  }
  
  set(key: string, template: string): void {
    this.cache.set(key, template);
    // Pre-compile template for faster execution
    this.compiled.set(key, this.compile(template));
  }
  
  private compile(template: string): Function {
    // Create optimized template function
    return (variables: Record<string, any>) => {
      return Object.entries(variables).reduce(
        (result, [key, value]) => 
          result.replace(new RegExp(`{{${key}}}`, 'g'), String(value)),
        template
      );
    };
  }
  
  execute(key: string, variables: Record<string, any>): string {
    const compiled = this.compiled.get(key);
    if (!compiled) {
      throw new Error(`Template not found: ${key}`);
    }
    return compiled(variables);
  }
}

// Global template cache
export const templateCache = new TemplateCache();

export async function processTemplateAsync(
  template: string,
  context: any,
  options: {
    streaming?: boolean;
    timeout?: number;
    retries?: number;
  } = {}
): Promise<string | AsyncGenerator<string>> {
  const {
    streaming = false,
    timeout = 30000,
    retries = 3
  } = options;
  
  const processWithRetry = async (attempt: number): Promise<string> => {
    try {
      const timeoutPromise = new Promise((_, reject) => {
        setTimeout(() => reject(new Error('Template processing timeout')), timeout);
      });
      
      const processingPromise = context.runtime.useModel(ModelType.TEXT_LARGE, {
        prompt: template,
        stream: streaming
      });
      
      return await Promise.race([processingPromise, timeoutPromise]);
      
    } catch (error) {
      if (attempt < retries) {
        console.warn(`Template processing failed, retrying (${attempt + 1}/${retries})`);
        await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
        return processWithRetry(attempt + 1);
      }
      throw error;
    }
  };
  
  return processWithRetry(0);
}

export function sanitizeTemplateInput(input: string): string {
  // Remove potential injection attacks
  return input
    .replace(/<script[^>]*>.*?<\/script>/gi, '')
    .replace(/javascript:/gi, '')
    .replace(/on\w+\s*=/gi, '')
    .replace(/\{\{[^}]*\}\}/g, match => {
      // Only allow whitelisted variables
      const allowedVars = ['agentName', 'providers', 'recentMessages'];
      const varName = match.slice(2, -2);
      return allowedVars.includes(varName) ? match : '';
    });
}

export function createFallbackTemplate(
  primaryTemplate: string,
  fallbackTemplate: string
): string {
  return `
  <task>
  Try processing with primary template, fall back to secondary if needed.
  </task>
  
  <primaryTemplate>
  ${primaryTemplate}
  </primaryTemplate>
  
  <fallbackTemplate>
  ${fallbackTemplate}
  </fallbackTemplate>
  
  <instructions>
  Attempt to process using the primary template. If that fails or produces invalid output, use the fallback template instead.
  </instructions>
  `;
}