Plugin Developer Guide

# Interactive plugin creation
elizaos create

# Or specify the name directly
elizaos create my-plugin --type plugin

plugin-my-plugin/
├── src/
│   ├── index.ts           # Plugin manifest
│   ├── actions/           # Your agent actions
│   │   └── example.ts
│   ├── providers/         # Context providers
│   │   └── example.ts
│   └── types/             # TypeScript types
│       └── index.ts
├── package.json           # Pre-configured with elizaos deps
├── tsconfig.json          # TypeScript config
├── tsup.config.ts         # Build configuration
└── README.md              # Plugin documentation

plugin-my-plugin/
├── src/
│   ├── index.ts           # Plugin manifest with routes
│   ├── actions/
│   ├── providers/
│   ├── types/
│   └── frontend/          # React frontend
│       ├── App.tsx
│       ├── main.tsx
│       └── components/
├── public/                # Static assets
├── index.html             # Frontend entry
├── vite.config.ts         # Vite configuration
├── tailwind.config.js     # Tailwind setup
└── [other config files]

# Navigate to your plugin
cd plugin-my-plugin

# Install dependencies (automatically done by CLI)
bun install

# Start development mode with hot reloading
elizaos dev

# Or start in production mode
elizaos start

# Build your plugin for distribution
bun run build

{
  "dependencies": {
    "@elizaos/plugin-knowledge": "workspace:*",
    "@yourorg/plugin-myplugin": "workspace:*"
  }
}

import { myPlugin } from '@yourorg/plugin-myplugin';

const agent = {
  name: 'MyAgent',
  plugins: [myPlugin],
};

# In your plugin directory (e.g., plugin-myplugin/)
bun install
bun run build
bun link

# In your project directory
cd packages/project-starter  # or wherever your agent project is
bun link @yourorg/plugin-myplugin

{
  "dependencies": {
    "@yourorg/plugin-myplugin": "link:@yourorg/plugin-myplugin"
  }
}

import { myPlugin } from '@yourorg/plugin-myplugin';

const agent = {
  name: 'MyAgent',
  plugins: [myPlugin],
};

import type { Plugin } from '@elizaos/core';

export interface Plugin {
  name: string;
  description: string;

  // Initialize plugin with runtime services
  init?: (config: Record<string, string>, runtime: IAgentRuntime) => Promise<void>;

  // Configuration
  config?: { [key: string]: any };

  // Services - Note: This is (typeof Service)[] not Service[]
  services?: (typeof Service)[];

  // Entity component definitions
  componentTypes?: {
    name: string;
    schema: Record<string, unknown>;
    validator?: (data: any) => boolean;
  }[];

  // Optional plugin features
  actions?: Action[];
  providers?: Provider[];
  evaluators?: Evaluator[];
  adapter?: IDatabaseAdapter;
  models?: {
    [key: string]: (...args: any[]) => Promise<any>;
  };
  events?: PluginEvents;
  routes?: Route[];
  tests?: TestSuite[];

  // Dependencies
  dependencies?: string[];
  testDependencies?: string[];

  // Plugin priority (higher priority plugins are loaded first)
  priority?: number;

  // Schema for validation
  schema?: any;
}

packages/plugin-<name>/
├── src/
│   ├── index.ts           # Plugin manifest and exports
│   ├── service.ts         # Main service implementation
│   ├── actions/           # Agent capabilities
│   │   └── *.ts
│   ├── providers/         # Context providers
│   │   └── *.ts
│   ├── evaluators/        # Post-processing
│   │   └── *.ts
│   ├── handlers/          # LLM model handlers
│   │   └── *.ts
│   ├── types/             # TypeScript definitions
│   │   └── index.ts
│   ├── constants/         # Configuration constants
│   │   └── index.ts
│   ├── utils/             # Helper functions
│   │   └── *.ts
│   └── tests.ts           # Test suite
├── __tests__/             # Unit tests
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md

import { Service, IAgentRuntime, logger } from '@elizaos/core';

export class MyService extends Service {
  static serviceType = 'my-service';
  capabilityDescription = 'Description of what this service provides';

  private client: any;
  private refreshInterval: NodeJS.Timer | null = null;

  constructor(protected runtime: IAgentRuntime) {
    super();
  }

  static async start(runtime: IAgentRuntime): Promise<MyService> {
    logger.info('Initializing MyService');
    const service = new MyService(runtime);

    // Initialize connections, clients, etc.
    await service.initialize();

    // Set up periodic tasks if needed
    service.refreshInterval = setInterval(
      () => service.refreshData(),
      60000 // 1 minute
    );

    return service;
  }

  async stop(): Promise<void> {
    // Cleanup resources
    if (this.refreshInterval) {
      clearInterval(this.refreshInterval);
    }
    // Close connections
    if (this.client) {
      await this.client.disconnect();
    }
    logger.info('MyService stopped');
  }

  private async initialize(): Promise<void> {
    // Service initialization logic
    const apiKey = this.runtime.getSetting('MY_API_KEY');
    if (!apiKey) {
      throw new Error('MY_API_KEY not configured');
    }

    this.client = new MyClient({ apiKey });
    await this.client.connect();
  }
}

export class MyService extends Service {
  static serviceType = 'my-service';

  static async start(runtime: IAgentRuntime): Promise<MyService> {
    const service = new MyService(runtime);

    // Immediate initialization
    await service.initialize();

    // Delayed initialization for non-critical tasks
    setTimeout(async () => {
      try {
        await service.loadCachedData();
        await service.syncWithRemote();
        logger.info('MyService: Delayed initialization complete');
      } catch (error) {
        logger.error('MyService: Delayed init failed', error);
        // Don't throw - service is still functional
      }
    }, 5000);

    return service;
  }
}

import {
  type Action,
  type ActionExample,
  type ActionResult,
  type HandlerCallback,
  type IAgentRuntime,
  type Memory,
  type State,
  ModelType,
  composePromptFromState,
  logger,
} from '@elizaos/core';

export const myAction: Action = {
  name: 'MY_ACTION',
  description: 'Clear, concise description for the LLM to understand when to use this',

  // Similes help with fuzzy matching - be creative!
  similes: ['SIMILAR_ACTION', 'ANOTHER_NAME', 'CASUAL_REFERENCE'],

  // Validation: Can this action run in the current context?
  validate: async (runtime: IAgentRuntime, message: Memory, state?: State): Promise<boolean> => {
    // Check permissions, settings, current state, etc.
    const hasPermission = await checkUserPermissions(runtime, message);
    const serviceAvailable = runtime.getService('my-service') !== null;

    return hasPermission && serviceAvailable;
  },

  // Handler: The brain of your action
  handler: async (
    runtime: IAgentRuntime,
    message: Memory,
    state?: State,
    options?: { [key: string]: unknown },
    callback?: HandlerCallback,
    responses?: Memory[]
  ): Promise<ActionResult> => {
    // ALWAYS return ActionResult with success field!
    try {
      // Access previous action results from multi-step chains
      const context = options?.context;
      const previousResults = context?.previousResults || [];

      // Get your state (providers have already run)
      if (!state) {
        state = await runtime.composeState(message, [
          'RECENT_MESSAGES',
          'CHARACTER',
          'ACTION_STATE', // Includes previous action results
        ]);
      }

      // Your action logic here
      const result = await doSomethingAmazing();

      // Use callback for intermediate responses
      if (callback) {
        await callback({
          text: `Working on it...`,
          actions: ['MY_ACTION'],
        });
      }

      // Return structured result
      return {
        success: true, // REQUIRED field
        text: `Action completed: ${result.summary}`,
        values: {
          // These merge into state for next actions
          lastActionTime: Date.now(),
          resultData: result.data,
        },
        data: {
          // Raw data for logging/debugging
          actionName: 'MY_ACTION',
          fullResult: result,
        },
      };
    } catch (error) {
      logger.error('Action failed:', error);

      return {
        success: false, // REQUIRED field
        text: 'Failed to complete action',
        error: error instanceof Error ? error : new Error(String(error)),
        data: {
          actionName: 'MY_ACTION',
          errorDetails: error.message,
        },
      };
    }
  },

  // Examples: Teach the LLM through scenarios
  examples: [
    [
      {
        name: '{{user1}}',
        content: { text: 'Can you do the thing?' },
      },
      {
        name: '{{agent}}',
        content: {
          text: "I'll do that for you right away!",
          actions: ['MY_ACTION'],
        },
      },
    ],
  ] as ActionExample[][],
};

export const muteRoomAction: Action = {
  name: 'MUTE_ROOM',
  similes: ['SHUT_UP', 'BE_QUIET', 'STOP_TALKING', 'SILENCE'],
  description: 'Mutes a room if asked to or if the agent is being annoying',

  validate: async (runtime, message) => {
    // Check if already muted
    const roomState = await runtime.getParticipantUserState(message.roomId, runtime.agentId);
    return roomState !== 'MUTED';
  },

  handler: async (runtime, message, state) => {
    // Create a decision prompt
    const shouldMuteTemplate = `# Task: Should {{agentName}} mute this room?

{{recentMessages}}

Should {{agentName}} mute and stop responding unless mentioned?

Respond YES if:
- User asked to stop/be quiet
- Agent responses are annoying users
- Conversation is hostile

Otherwise NO.`;

    const prompt = composePromptFromState({ state, template: shouldMuteTemplate });
    const decision = await runtime.useModel(ModelType.TEXT_SMALL, {
      prompt,
      runtime,
    });

    if (decision.toLowerCase().includes('yes')) {
      await runtime.setParticipantUserState(message.roomId, runtime.agentId, 'MUTED');

      return {
        success: true,
        text: 'Going silent in this room',
        values: { roomMuted: true },
      };
    }

    return {
      success: true,
      text: 'Continuing to participate',
      values: { roomMuted: false },
    };
  },
};

export const sendMessageAction: Action = {
  name: 'SEND_MESSAGE',
  similes: ['DM', 'MESSAGE', 'PING', 'TELL', 'NOTIFY'],
  description: 'Send a message to a user or room on any platform',

  handler: async (runtime, message, state, options, callback) => {
    // Extract target using LLM
    const targetPrompt = composePromptFromState({
      state,
      template: `Extract message target from: {{recentMessages}}
Return JSON:
{
  "targetType": "user|room",
  "source": "platform",
  "identifiers": { "username": "...", "roomName": "..." }
}`,
    });

    const targetData = await runtime.useModel(ModelType.OBJECT_LARGE, {
      prompt: targetPrompt,
      schema: targetSchema,
    });

    // Route to appropriate service
    if (targetData.targetType === 'user') {
      const user = await findEntityByName(runtime, message, state);
      const service = runtime.getService(targetData.source);

      await service.sendDirectMessage(runtime, user.id, message.content.text);

      return {
        success: true,
        text: `Message sent to ${user.names[0]}`,
        values: { messageSent: true, targetUser: user.names[0] },
      };
    }

    // Handle room messages similarly...
  },
};

export const replyAction: Action = {
  name: 'REPLY',
  similes: ['RESPOND', 'ANSWER', 'SPEAK', 'SAY'],
  description: 'Generate and send a response to the conversation',

  validate: async () => true, // Always valid

  handler: async (runtime, message, state, options, callback) => {
    // Access chain context
    const previousActions = options?.context?.previousResults || [];

    // Include dynamic providers from previous actions
    const dynamicProviders = responses?.flatMap((r) => r.content?.providers ?? []) ?? [];

    // Compose state with action results
    state = await runtime.composeState(message, [
      ...dynamicProviders,
      'RECENT_MESSAGES',
      'ACTION_STATE', // Includes previous action results
    ]);

    const replyTemplate = `# Generate response as {{agentName}}

{{providers}}

Previous actions taken: {{actionResults}}

Generate thoughtful response considering the context and any actions performed.

\`\`\`json
{
  "thought": "reasoning about response",
  "message": "the actual response"
}
\`\`\``;

    const response = await runtime.useModel(ModelType.OBJECT_LARGE, {
      prompt: composePromptFromState({ state, template: replyTemplate }),
    });

    await callback({
      text: response.message,
      thought: response.thought,
      actions: ['REPLY'],
    });

    return {
      success: true,
      text: 'Reply sent',
      values: {
        lastReply: response.message,
        thoughtProcess: response.thought,
      },
    };
  },
};

export const updateRoleAction: Action = {
  name: 'UPDATE_ROLE',
  similes: ['MAKE_ADMIN', 'CHANGE_PERMISSIONS', 'PROMOTE', 'DEMOTE'],
  description: 'Update user roles with permission validation',

  validate: async (runtime, message) => {
    // Only in group contexts with server ID
    return message.content.channelType === ChannelType.GROUP && !!message.content.serverId;
  },

  handler: async (runtime, message, state) => {
    // Get requester's role
    const world = await runtime.getWorld(worldId);
    const requesterRole = world.metadata?.roles[message.entityId] || Role.NONE;

    // Extract role changes using LLM
    const changes = await runtime.useModel(ModelType.OBJECT_LARGE, {
      prompt: 'Extract role assignments from: ' + state.text,
      schema: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            entityId: { type: 'string' },
            newRole: {
              type: 'string',
              enum: ['OWNER', 'ADMIN', 'NONE'],
            },
          },
        },
      },
    });

    // Validate each change
    const results = [];
    for (const change of changes) {
      if (canModifyRole(requesterRole, currentRole, change.newRole)) {
        world.metadata.roles[change.entityId] = change.newRole;
        results.push({ success: true, ...change });
      } else {
        results.push({
          success: false,
          reason: 'Insufficient permissions',
          ...change,
        });
      }
    }

    await runtime.updateWorld(world);

    return {
      success: results.some((r) => r.success),
      text: `Updated ${results.filter((r) => r.success).length} roles`,
      data: { results },
    };
  },
};

interface ActionResult {
  // REQUIRED: Indicates if the action succeeded
  success: boolean;

  // Optional: User-facing message about what happened
  text?: string;

  // Optional: Values to merge into state for subsequent actions
  values?: Record<string, any>;

  // Optional: Raw data for logging/debugging
  data?: Record<string, any>;

  // Optional: Error information if action failed
  error?: string | Error;
}

// 1. Provider phase - gather context
const state = await runtime.composeState(message, ['ACTIONS']);

// 2. Action selection - LLM chooses based on available actions
const validActions = await getValidActions(runtime, message, state);

// 3. Action execution - may include multiple actions
await runtime.processActions(message, responses, state, callback);

// 4. State accumulation - each action's values merge into state
// Action 1 returns: { values: { step1Complete: true } }
// Action 2 receives: state.values.step1Complete === true

// 5. Evaluator phase - post-processing
await runtime.evaluate(message, state, true, callback, responses);

// Actions can register other actions dynamically
export const pluginLoaderAction: Action = {
  name: 'LOAD_PLUGIN',

  handler: async (runtime, message, state) => {
    const pluginName = extractPluginName(state);
    const plugin = await import(pluginName);

    // Register new actions from the loaded plugin
    if (plugin.actions) {
      for (const action of plugin.actions) {
        runtime.registerAction(action);
      }
    }

    return {
      success: true,
      text: `Loaded ${plugin.actions.length} new actions`,
      values: {
        loadedPlugin: pluginName,
        newActions: plugin.actions.map((a) => a.name),
      },
    };
  },
};

export const conditionalWorkflow: Action = {
  name: 'SMART_WORKFLOW',

  handler: async (runtime, message, state, options, callback) => {
    // Step 1: Analyze
    const analysis = await analyzeRequest(state);

    if (analysis.requiresApproval) {
      // Trigger approval action
      await callback({
        text: 'This requires approval',
        actions: ['REQUEST_APPROVAL'],
      });

      return {
        success: true,
        values: {
          workflowPaused: true,
          pendingApproval: true,
        },
      };
    }

    // Step 2: Execute
    if (analysis.complexity === 'simple') {
      return await executeSimpleTask(runtime, analysis);
    } else {
      // Trigger complex workflow
      await callback({
        text: 'Starting complex workflow',
        actions: ['COMPLEX_WORKFLOW'],
      });

      return {
        success: true,
        values: {
          workflowType: 'complex',
          analysisData: analysis,
        },
      };
    }
  },
};

// Compose multiple actions into higher-level operations
export const compositeAction: Action = {
  name: 'SEND_AND_TRACK',
  description: 'Send a message and track its delivery',

  handler: async (runtime, message, state, options, callback) => {
    // Execute sub-actions
    const sendResult = await sendMessageAction.handler(runtime, message, state, options, callback);

    if (!sendResult.success) {
      return sendResult; // Propagate failure
    }

    // Track the sent message
    const trackingId = generateTrackingId();
    await runtime.createMemory(
      {
        id: trackingId,
        entityId: message.entityId,
        roomId: message.roomId,
        content: {
          type: 'message_tracking',
          sentTo: sendResult.data.targetId,
          sentAt: Date.now(),
          messageContent: sendResult.data.messageContent,
        },
      },
      'tracking'
    );

    return {
      success: true,
      text: `Message sent and tracked (${trackingId})`,
      values: {
        ...sendResult.values,
        trackingId,
        tracked: true,
      },
      data: {
        sendResult,
        trackingId,
      },
    };
  },
};

export const learningAction: Action = {
  name: 'ADAPTIVE_RESPONSE',

  handler: async (runtime, message, state) => {
    // Retrieve past performance
    const history = await runtime.getMemories({
      tableName: 'action_feedback',
      roomId: message.roomId,
      count: 100,
    });

    // Analyze what worked well
    const analysis = await runtime.useModel(ModelType.TEXT_LARGE, {
      prompt: `Analyze these past interactions and identify patterns:
${JSON.stringify(history)}
What response strategies were most effective?`,
    });

    // Adapt behavior based on learning
    const strategy = determineStrategy(analysis);
    const response = await generateResponse(state, strategy);

    // Store for future learning
    await runtime.createMemory(
      {
        id: generateId(),
        content: {
          type: 'action_feedback',
          strategy: strategy.name,
          context: state.text,
          response: response.text,
        },
      },
      'action_feedback'
    );

    return {
      success: true,
      text: response.text,
      values: {
        strategyUsed: strategy.name,
        confidence: strategy.confidence,
      },
    };
  },
};

// __tests__/myAction.test.ts
import { describe, it, expect, beforeEach } from 'bun:test';
import { myAction } from '../src/actions/myAction';
import { createMockRuntime } from '@elizaos/test-utils';
import { ActionResult, Memory, State } from '@elizaos/core';

describe('MyAction', () => {
  let mockRuntime: any;
  let mockMessage: Memory;
  let mockState: State;

  beforeEach(() => {
    mockRuntime = createMockRuntime({
      settings: { MY_API_KEY: 'test-key' },
    });

    mockMessage = {
      id: 'test-id',
      entityId: 'user-123',
      roomId: 'room-456',
      content: { text: 'Do the thing' },
    };

    mockState = {
      values: { recentMessages: 'test context' },
      data: { room: { name: 'Test Room' } },
      text: 'State text',
    };
  });

  describe('validation', () => {
    it('should validate when all requirements are met', async () => {
      const isValid = await myAction.validate(mockRuntime, mockMessage, mockState);
      expect(isValid).toBe(true);
    });

    it('should not validate without required service', async () => {
      mockRuntime.getService = () => null;
      const isValid = await myAction.validate(mockRuntime, mockMessage, mockState);
      expect(isValid).toBe(false);
    });
  });

  describe('handler', () => {
    it('should return success ActionResult on successful execution', async () => {
      const mockCallback = jest.fn();

      const result = await myAction.handler(mockRuntime, mockMessage, mockState, {}, mockCallback);

      expect(result.success).toBe(true);
      expect(result.text).toContain('completed');
      expect(result.values).toHaveProperty('lastActionTime');
      expect(mockCallback).toHaveBeenCalled();
    });

    it('should handle errors gracefully', async () => {
      // Make service throw error
      mockRuntime.getService = () => {
        throw new Error('Service unavailable');
      };

      const result = await myAction.handler(mockRuntime, mockMessage, mockState);

      expect(result.success).toBe(false);
      expect(result.error).toBeDefined();
      expect(result.text).toContain('Failed');
    });

    it('should access previous action results', async () => {
      const previousResults: ActionResult[] = [
        {
          success: true,
          values: { previousData: 'test' },
          data: { actionName: 'PREVIOUS_ACTION' },
        },
      ];

      const result = await myAction.handler(mockRuntime, mockMessage, mockState, {
        context: { previousResults },
      });

      // Verify it used previous results
      expect(result.values?.usedPreviousData).toBe(true);
    });
  });

  describe('examples', () => {
    it('should have valid example structure', () => {
      expect(myAction.examples).toBeDefined();
      expect(Array.isArray(myAction.examples)).toBe(true);

      // Each example should be a conversation array
      for (const example of myAction.examples!) {
        expect(Array.isArray(example)).toBe(true);

        // Each message should have name and content
        for (const message of example) {
          expect(message).toHaveProperty('name');
          expect(message).toHaveProperty('content');
        }
      }
    });
  });
});

// tests/e2e/myAction.e2e.ts
export const myActionE2ETests = {
  name: 'MyAction E2E Tests',
  tests: [
    {
      name: 'should execute full action flow',
      fn: async (runtime: IAgentRuntime) => {
        // Create test message
        const message: Memory = {
          id: generateId(),
          entityId: 'test-user',
          roomId: runtime.agentId,
          content: {
            text: 'Please do the thing',
            source: 'test',
          },
        };

        // Store message
        await runtime.createMemory(message, 'messages');

        // Compose state
        const state = await runtime.composeState(message);

        // Execute action
        const result = await myAction.handler(runtime, message, state, {}, async (response) => {
          // Verify callback responses
          expect(response.text).toBeDefined();
        });

        // Verify result
        expect(result.success).toBe(true);

        // Verify side effects
        const memories = await runtime.getMemories({
          roomId: message.roomId,
          tableName: 'action_results',
          count: 1,
        });

        expect(memories.length).toBeGreaterThan(0);
      },
    },
  ],
};

import { Provider, ProviderResult, IAgentRuntime, Memory, State, addHeader } from '@elizaos/core';

export const myProvider: Provider = {
  name: 'myProvider',
  description: 'Provides contextual information about X',

  // Optional: Set to true if this provider should only run when explicitly requested
  dynamic: false,

  // Optional: Control execution order (lower numbers run first, can be negative)
  position: 100,

  // Optional: Set to true to exclude from default provider list
  private: false,

  get: async (runtime: IAgentRuntime, message: Memory, state: State): Promise<ProviderResult> => {
    try {
      const service = runtime.getService('my-service') as MyService;
      const data = await service.getCurrentData();

      // Format data for LLM context
      const formattedText = addHeader(
        '# Current System Status',
        `Field 1: ${data.field1}
Field 2: ${data.field2}
Last updated: ${new Date(data.timestamp).toLocaleString()}`
      );

      return {
        // Text that will be included in the LLM prompt
        text: formattedText,

        // Values that can be accessed by other providers/actions
        values: {
          currentField1: data.field1,
          currentField2: data.field2,
          lastUpdate: data.timestamp,
        },

        // Raw data for internal use
        data: {
          raw: data,
          processed: true,
        },
      };
    } catch (error) {
      return {
        text: 'Unable to retrieve current status',
        values: {},
        data: { error: error.message },
      };
    }
  },
};

export const recentMessagesProvider: Provider = {
  name: 'RECENT_MESSAGES',
  description: 'Recent messages, interactions and other memories',
  position: 100, // Runs after most other providers

  get: async (runtime, message) => {
    const messages = await runtime.getMemories({
      roomId: message.roomId,
      count: runtime.getConversationLength(),
      unique: false,
    });

    const formattedMessages = formatMessages(messages);

    return {
      text: addHeader('# Conversation Messages', formattedMessages),
      values: { recentMessages: formattedMessages },
      data: { messages },
    };
  },
};

export const actionsProvider: Provider = {
  name: 'ACTIONS',
  description: 'Possible response actions',
  position: -1, // Runs early to inform other providers

  get: async (runtime, message, state) => {
    // Get all valid actions for this context
    const validActions = await Promise.all(
      runtime.actions.map(async (action) => {
        const isValid = await action.validate(runtime, message, state);
        return isValid ? action : null;
      })
    );

    const actions = validActions.filter(Boolean);
    const actionNames = formatActionNames(actions);

    return {
      text: `Possible response actions: ${actionNames}`,
      values: { actionNames },
      data: { actionsData: actions },
    };
  },
};

export const knowledgeProvider: Provider = {
  name: 'KNOWLEDGE',
  description: 'Knowledge from the knowledge base',
  dynamic: true, // Only runs when explicitly requested

  get: async (runtime, message) => {
    const knowledgeService = runtime.getService('knowledge');
    const relevantKnowledge = await knowledgeService.search(message.content.text);

    if (!relevantKnowledge.length) {
      return { text: '', values: {}, data: {} };
    }

    return {
      text: addHeader('# Relevant Knowledge', formatKnowledge(relevantKnowledge)),
      values: { knowledgeUsed: true },
      data: { knowledge: relevantKnowledge },
    };
  },
};

import { Evaluator, IAgentRuntime, Memory, State, HandlerCallback } from '@elizaos/core';

export const myEvaluator: Evaluator = {
  name: 'myEvaluator',
  description: 'Analyzes responses for quality and extracts insights',

  // Examples help the LLM understand when to use this evaluator
  examples: [
    {
      prompt: 'User asks about product pricing',
      messages: [
        { name: 'user', content: { text: 'How much does it cost?' } },
        { name: 'assistant', content: { text: 'The price is $99' } },
      ],
      outcome: 'Extract pricing information for future reference',
    },
  ],

  // Similar descriptions for fuzzy matching
  similes: ['RESPONSE_ANALYZER', 'QUALITY_CHECK'],

  // Optional: Run even if the agent didn't respond
  alwaysRun: false,

  // Validation: Determines if evaluator should run
  validate: async (runtime: IAgentRuntime, message: Memory, state?: State): Promise<boolean> => {
    // Example: Only run for certain types of responses
    return message.content?.text?.includes('transaction') || false;
  },

  // Handler: Main evaluation logic
  handler: async (
    runtime: IAgentRuntime,
    message: Memory,
    state?: State,
    options?: { [key: string]: unknown },
    callback?: HandlerCallback,
    responses?: Memory[]
  ): Promise<void> => {
    try {
      // Analyze the response
      const responseText = responses?.[0]?.content?.text || '';

      if (responseText.includes('transaction')) {
        // Extract and store transaction data
        const txHash = extractTransactionHash(responseText);

        if (txHash) {
          // Store for future reference
          await runtime.createMemory(
            {
              id: generateId(),
              entityId: message.entityId,
              roomId: message.roomId,
              content: {
                text: `Transaction processed: ${txHash}`,
                type: 'transaction_record',
                data: { txHash, timestamp: Date.now() },
              },
            },
            'facts'
          );

          // Log the evaluation
          await runtime.adapter.log({
            entityId: message.entityId,
            roomId: message.roomId,
            type: 'evaluator',
            body: {
              evaluator: 'myEvaluator',
              result: 'transaction_extracted',
              txHash,
            },
          });
        }
      }

      // Can also trigger follow-up actions via callback
      if (callback) {
        callback({
          text: 'Analysis complete',
          content: { analyzed: true },
        });
      }
    } catch (error) {
      runtime.logger.error('Evaluator error:', error);
    }
  },
};

export const factExtractor: Evaluator = {
  name: 'FACT_EXTRACTOR',
  description: 'Extracts facts from conversations for long-term memory',
  alwaysRun: true, // Run after every response

  validate: async () => true, // Always valid

  handler: async (runtime, message, state, options, callback, responses) => {
    const facts = await extractFactsFromConversation(runtime, message, responses);

    for (const fact of facts) {
      await runtime.createMemory(
        {
          id: generateId(),
          entityId: message.entityId,
          roomId: message.roomId,
          content: {
            text: fact.statement,
            type: 'fact',
            confidence: fact.confidence,
          },
        },
        'facts',
        true
      ); // unique = true to avoid duplicates
    }
  },
};

export const qualityEvaluator: Evaluator = {
  name: 'QUALITY_CHECK',
  description: 'Evaluates response quality and coherence',

  validate: async (runtime, message) => {
    // Only evaluate responses to direct questions
    return message.content?.text?.includes('?') || false;
  },

  handler: async (runtime, message, state, options, callback, responses) => {
    const quality = await assessResponseQuality(responses[0]);

    if (quality.score < 0.7) {
      // Log low quality response for review
      await runtime.adapter.log({
        entityId: message.entityId,
        roomId: message.roomId,
        type: 'quality_alert',
        body: {
          score: quality.score,
          issues: quality.issues,
          responseId: responses[0].id,
        },
      });
    }
  },
};

// Example flow in pseudocode
async function processMessage(message: Memory) {
  // 1. Compose state with providers
  const state = await runtime.composeState(message, ['RECENT_MESSAGES', 'CHARACTER', 'ACTIONS']);

  // 2. Generate response using LLM with composed state
  const response = await generateResponse(state);

  // 3. Execute any actions the LLM chose
  if (response.actions?.length > 0) {
    await runtime.processActions(message, [response], state);
  }

  // 4. Run evaluators on the response
  await runtime.evaluate(message, state, true, callback, [response]);
}

export const myAction: Action = {
  name: 'MY_ACTION',

  handler: async (runtime, message, state, options, callback) => {
    // Access provider values
    const recentMessages = state.values?.recentMessages;
    const actionNames = state.values?.actionNames;

    // Access raw provider data
    const providerData = state.data?.providers;
    if (providerData) {
      // Get specific provider's data
      const knowledgeData = providerData['KNOWLEDGE']?.data;
      const characterData = providerData['CHARACTER']?.data;
    }

    // Access action execution context
    const previousResults = state.data?.actionResults || [];
    const actionPlan = state.data?.actionPlan;

    // Use the data to make decisions
    if (state.values?.knowledgeUsed) {
      // Knowledge was found, incorporate it
    }
  },
};

// Include only specific providers
const state = await runtime.composeState(message, ['CHARACTER', 'KNOWLEDGE'], true);

// Add extra providers to the default set
const state = await runtime.composeState(message, ['KNOWLEDGE', 'CUSTOM_PROVIDER']);

// Skip cache and regenerate
const state = await runtime.composeState(message, null, false, true);

import { ModelType, GenerateTextParams, EventType } from '@elizaos/core';

export const models = {
  [ModelType.TEXT_SMALL]: async (
    runtime: IAgentRuntime,
    params: GenerateTextParams
  ): Promise<string> => {
    const client = createClient(runtime);
    const { text, usage } = await client.generateText({
      model: getSmallModel(runtime),
      prompt: params.prompt,
      temperature: params.temperature ?? 0.7,
      maxTokens: params.maxTokens ?? 4096,
    });

    // Emit usage event
    runtime.emitEvent(EventType.MODEL_USED, {
      provider: 'my-llm',
      type: ModelType.TEXT_SMALL,
      tokens: usage,
    });

    return text;
  },

  [ModelType.TEXT_EMBEDDING]: async (
    runtime: IAgentRuntime,
    params: TextEmbeddingParams | string | null
  ): Promise<number[]> => {
    if (params === null) {
      // Return test embedding
      return Array(1536).fill(0);
    }

    const text = typeof params === 'string' ? params : params.text;
    const embedding = await client.createEmbedding(text);
    return embedding;
  },
};

import { Plugin, Route, IAgentRuntime } from '@elizaos/core';

// Define route handlers
async function statusHandler(req: any, res: any, runtime: IAgentRuntime) {
  try {
    const service = runtime.getService('my-service') as MyService;
    const status = await service.getStatus();

    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(
      JSON.stringify({
        success: true,
        data: status,
        timestamp: new Date().toISOString(),
      })
    );
  } catch (error) {
    res.writeHead(500, { 'Content-Type': 'application/json' });
    res.end(
      JSON.stringify({
        success: false,
        error: error.message,
      })
    );
  }
}

// Export routes array
export const myPluginRoutes: Route[] = [
  {
    type: 'GET',
    path: '/api/status',
    handler: statusHandler,
    public: true, // Makes this route discoverable in UI
    name: 'API Status', // Display name for UI tab
  },
  {
    type: 'POST',
    path: '/api/webhook',
    handler: webhookHandler,
  },
];

// Include routes in plugin definition
export const myPlugin: Plugin = {
  name: 'my-plugin',
  description: 'My plugin with HTTP routes',
  services: [MyService],
  routes: myPluginRoutes, // Add routes here
};

// Helper functions for standardized responses
function sendSuccess(res: any, data: any, status = 200) {
  res.writeHead(status, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ success: true, data }));
}

function sendError(res: any, status: number, message: string, details?: any) {
  res.writeHead(status, { 'Content-Type': 'application/json' });
  res.end(
    JSON.stringify({
      success: false,
      error: { message, details },
    })
  );
}

// Use in handlers
async function apiHandler(req: any, res: any, runtime: IAgentRuntime) {
  try {
    const result = await processRequest(req.body);
    sendSuccess(res, result);
  } catch (error) {
    sendError(res, 500, 'Processing failed', error.message);
  }
}