What are Evaluators?

Evaluators = post-processors that analyze and extract information from conversations.

Evaluator Interface

interface Evaluator {
  name: string;              // Unique identifier
  description: string;       // What it evaluates
  similes?: string[];       // Alternative names
  alwaysRun?: boolean;      // Run on every message?
  examples: EvaluationExample[];  // Training examples
  validate: Validator;       // Should this run?
  handler: Handler;          // Process the response
}

Core Evaluators (Bootstrap Plugin)

EvaluatorPurposeExtracts
reflectionEvaluatorSelf-awarenessInsights about interactions
factEvaluatorFact extractionImportant information
goalEvaluatorGoal trackingUser objectives

Plugin Evaluator Examples

EvaluatorPluginPurpose
sentimentEvaluatorplugin-sentimentTrack conversation mood
toxicityEvaluatorplugin-moderationFilter harmful content
tokenPriceEvaluatorplugin-dexscreenerDetect price queries
summaryEvaluatorplugin-knowledgeSummarize conversations

Evaluator Flow

Common Use Cases

  • Extract facts from conversations
  • Track user preferences
  • Update relationship status
  • Record important events

Creating Evaluators

Basic Evaluator

const evaluator: Evaluator = {
  name: 'my-evaluator',
  description: 'Processes responses',
  examples: [],  // Training examples
  
  validate: async (runtime, message) => {
    return true;  // Run on all messages
  },
  
  handler: async (runtime, message) => {
    // Process and extract
    const result = await analyze(message);
    // Store findings
    await storeResult(result);
    return result;
  }
};

With Examples

const evaluator: Evaluator = {
  name: 'fact-extractor',
  description: 'Extracts facts from conversations',
  examples: [{
    prompt: 'Extract facts from this conversation',
    messages: [
      { name: 'user', content: { text: 'I live in NYC' } },
      { name: 'agent', content: { text: 'NYC is a great city!' } }
    ],
    outcome: 'User lives in New York City'
  }],
  validate: async () => true,
  handler: async (runtime, message, state) => {
    const facts = await extractFacts(state);
    for (const fact of facts) {
      await runtime.factsManager.addFact(fact);
    }
    return facts;
  }
};

Best Practices

  • Run evaluators async (don’t block responses)
  • Store extracted data for future context
  • Use alwaysRun: true sparingly
  • Provide clear examples for training
  • Keep handlers lightweight

Next Steps