Plugin Interface

interface Plugin {
  name: string;
  description: string;
  init?: (config: Record<string, string>, runtime: IAgentRuntime) => Promise<void>;
  config?: Record<string, string | number | boolean | null>;
  services?: ServiceClass[];
  componentTypes?: ComponentTypeDefinition[];
  actions?: Action[];
  providers?: Provider[];
  evaluators?: Evaluator[];
  adapter?: IDatabaseAdapter;
  models?: {
    [K in keyof ModelParamsMap]?: (
      runtime: IAgentRuntime,
      params: ModelParamsMap[K]
    ) => Promise<PluginModelResult<K>>;
  };
  events?: PluginEvents;
  routes?: Route[];
  tests?: TestSuite[];
  dependencies?: string[];
  testDependencies?: string[];
  priority?: number;
  schema?: Record<string, JsonValue | object>;
}

name: "@elizaos/plugin-example"

description: "Provides Twitter integration for social media interactions"

init: async (config, runtime) => {
  // Validate required environment variables
  const apiKey = runtime.getSetting("TWITTER_API_KEY");
  if (!apiKey) {
    throw new Error("TWITTER_API_KEY required");
  }
  
  // Register custom model handler
  runtime.registerModel(
    "TWITTER_SENTIMENT",
    async (runtime, params) => {
      // Custom model implementation
      return { sentiment: "positive", score: 0.85 };
    },
    "plugin-twitter",
    10 // priority
  );
  
  runtime.logger.success("Twitter plugin initialized");
}

config: {
  maxRetries: 3,
  timeout: 5000,
  enableCaching: true,
  apiVersion: "v2"
}

actions: [
  {
    name: "SEND_TWEET",
    description: "Post a tweet to Twitter",
    handler: async (runtime, message, state, options, callback) => {
      const text = options?.parameters?.text as string;
      // Send tweet implementation
      return {
        success: true,
        text: `Tweet posted: ${text}`
      };
    },
    validate: async (runtime, message, state) => {
      // Validation logic
      return true;
    },
    parameters: [
      {
        name: "text",
        description: "The tweet content to post",
        required: true,
        schema: { type: "string", maxLength: 280 }
      }
    ]
  }
]

providers: [
  {
    name: "TWITTER_PROFILE",
    description: "Provides Twitter profile information",
    get: async (runtime, message, state) => {
      const profile = await fetchTwitterProfile(runtime);
      return {
        text: `Twitter: @${profile.username} (${profile.followers} followers)`,
        values: {
          twitterUsername: profile.username,
          twitterFollowers: profile.followers
        },
        data: { profile }
      };
    }
  }
]

evaluators: [
  {
    name: "TWITTER_SENTIMENT",
    description: "Analyzes sentiment of tweets",
    phase: "post", // or "pre"
    alwaysRun: false,
    handler: async (runtime, message, state) => {
      // Sentiment analysis implementation
      return {
        success: true,
        values: { sentiment: "positive" }
      };
    },
    validate: async (runtime, message, state) => {
      return message.content.source === "twitter";
    },
    examples: []
  }
]

services: [
  class TwitterService extends Service {
    static serviceType = "twitter";
    
    constructor(runtime?: IAgentRuntime) {
      super();
    }
    
    static async start(runtime: IAgentRuntime): Promise<Service> {
      const service = new TwitterService(runtime);
      // Initialize service
      return service;
    }
    
    async stop(): Promise<void> {
      // Cleanup
    }
  }
]

models: {
  TEXT_SMALL: async (runtime, params) => {
    // Custom LLM implementation
    const response = await callCustomLLM(params.prompt);
    return response;
  },
  IMAGE_DESCRIPTION: async (runtime, params) => {
    // Custom vision model
    return {
      description: "A photo of...",
      title: "Image"
    };
  }
}

events: {
  [EventType.MESSAGE_RECEIVED]: [
    async (payload: MessagePayload) => {
      console.log("Message received:", payload.message.content.text);
    }
  ],
  [EventType.WORLD_JOINED]: [
    async (payload: WorldPayload) => {
      console.log("Joined world:", payload.world.name);
    }
  ]
}

routes: [
  {
    type: "POST",
    path: "/api/twitter/webhook",
    public: false,
    handler: async (req, res, runtime) => {
      const event = req.body;
      // Process webhook
      res.json({ success: true });
    }
  },
  {
    type: "GET",
    path: "/api/twitter/status",
    public: true,
    name: "twitter-status",
    handler: async (req, res, runtime) => {
      res.json({ status: "connected" });
    }
  }
]

dependencies: ["@elizaos/plugin-node"]

testDependencies: ["@elizaos/plugin-test-utils"]

priority: 10

import { Plugin, Action, Provider, Service, EventType } from "@elizaos/core";

export const twitterPlugin: Plugin = {
  name: "@elizaos/plugin-twitter",
  description: "Twitter integration for social media interactions",
  
  init: async (config, runtime) => {
    const apiKey = runtime.getSetting("TWITTER_API_KEY");
    if (!apiKey) {
      throw new Error("TWITTER_API_KEY required");
    }
    runtime.logger.success("Twitter plugin initialized");
  },
  
  actions: [
    {
      name: "SEND_TWEET",
      description: "Post a tweet to Twitter",
      handler: async (runtime, message, state, options) => {
        const text = options?.parameters?.text as string;
        return { success: true, text: `Tweet posted: ${text}` };
      },
      validate: async () => true,
      parameters: [
        {
          name: "text",
          description: "Tweet content",
          required: true,
          schema: { type: "string", maxLength: 280 }
        }
      ]
    }
  ],
  
  providers: [
    {
      name: "TWITTER_PROFILE",
      get: async (runtime, message, state) => {
        return {
          text: "Twitter profile data",
          values: { username: "agent" }
        };
      }
    }
  ],
  
  services: [TwitterService],
  
  events: {
    [EventType.MESSAGE_SENT]: [
      async (payload) => {
        console.log("Message sent to Twitter");
      }
    ]
  },
  
  dependencies: ["@elizaos/plugin-node"]
};