README.md

ElizaOS Registry

Intro

Eliza now supports dynamic plugin loading directly from the package registry.

Available Plugins

All official plugins are hosted at github.com/elizaos-plugins. Currently available plugins include:

• @elizaos/plugin-solana - Solana blockchain integration
• @elizaos/client-discord - Discord bot integration
• @elizaos/client-twitter - Twitter bot integration
• @elizaos/plugin-whatsapp - WhatsApp integration
• @elizaos/plugin-browser - Web scraping capabilities
• @elizaos/plugin-pdf - PDF processing
• @elizaos/plugin-image - Image processing and analysis
• @elizaos/plugin-video - Video processing capabilities
• @elizaos/plugin-llama - Local LLaMA model integration

Visit the our Registry Hub

Adding Plugins on eliza

1. package.json:

{
  "dependencies": {
    "@elizaos/plugin-solana": "github:elizaos-plugins/plugin-solana",
    "@elizaos/plugin-twitter": "github:elizaos-plugins/plugin-twitter"
  }
}

2. Character configuration:

{
  "name": "MyAgent",
  "plugins": [
    "@elizaos/plugin-solana",
    "@elizaos/plugin-twitter"
  ]
}

Plugin Architecture

Plugin Development

Eliza uses a unified plugin architecture where everything is a plugin - including clients, adapters, actions, evaluators, and services. This approach ensures consistent behavior and better extensibility. Here's how the architecture works:

1. Plugin Types: Each plugin can provide one or more of the following:

   • Clients (e.g., Discord, Twitter, WhatsApp integrations)
   • Adapters (e.g., database adapters, caching systems)
   • Actions (custom functionality)
   • Evaluators (decision-making components)
   • Services (background processes)
   • Providers (data or functionality providers)

2. Plugin Interface: All plugins implement the core Plugin interface:

   type Plugin = {
       name: string;
       description: string;
       config?: { [key: string]: any };
       actions?: Action[];
       providers?: Provider[];
       evaluators?: Evaluator[];
       services?: Service[];
       clients?: Client[];
       adapters?: Adapter[];
   };

3. Independent Repositories: Each plugin lives in its own repository under the elizaos-plugins organization, allowing:

   • Independent versioning and releases
   • Focused issue tracking and documentation
   • Easier maintenance and contribution
   • Separate CI/CD pipelines

4. Plugin Structure: Each plugin repository should follow this structure:

   plugin-name/
   ├── images/
   │   ├── logo.jpg        # Plugin branding logo
   │   ├── banner.jpg      # Plugin banner image
   ├── src/
   │   ├── index.ts        # Main plugin entry point
   │   ├── actions/        # Plugin-specific actions
   │   ├── clients/        # Client implementations
   │   ├── adapters/       # Adapter implementations
   │   └── types.ts        # Type definitions
   │   └── environment.ts  # runtime.getSetting, zod validation
   ├── package.json        # Plugin dependencies
   └── README.md          # Plugin documentation
   

5. Package Configuration: Your plugin's package.json must include an agentConfig section:

   {
     "name": "@elizaos/plugin-example",
     "version": "1.0.0",
     "agentConfig": {
       "pluginType": "elizaos:plugin:1.0.0",
       "pluginParameters": {
         "API_KEY": {
           "type": "string",
           "description": "API key for the service"
         }
       }
     }
   }

6. Plugin Loading: Plugins are dynamically loaded at runtime through the handlePluginImporting function, which:

   • Imports the plugin module
   • Reads the plugin configuration
   • Validates plugin parameters
   • Registers the plugin's components (clients, adapters, actions, etc.)

7. Client and Adapter Implementation: When implementing clients or adapters:

   // Client example
   const discordPlugin: Plugin = {
     name: "discord",
     description: "Discord client plugin",
     clients: [DiscordClientInterface]
   };

   // Adapter example
   const postgresPlugin: Plugin = {
     name: "postgres",
     description: "PostgreSQL database adapter",
     adapters: [PostgresDatabaseAdapter]
   };
   
   // Adapter example
   export const browserPlugin = {
    name: "default",
    description: "Pdf",
    services: [PdfService],
    actions: [],
  };

Environment Variables and Secrets

Plugins can access environment variables and secrets in two ways:

1. Character Configuration: Through agent.json.secret or character settings:

   {
     "name": "MyAgent",
     "settings": {
       "secrets": {
         "PLUGIN_API_KEY": "your-api-key",
         "PLUGIN_SECRET": "your-secret"
       }
     }
   }

2. Runtime Access: Plugins can access their configuration through the runtime:

   class MyPlugin implements Plugin {
     async initialize(runtime: AgentRuntime) {
       const apiKey = runtime.getSetting("PLUGIN_API_KEY");
       const secret = runtime.getSetting("PLUGIN_SECRET");
     }
   }

The getSetting method follows this precedence:

1. Character settings secrets
2. Character settings
3. Global settings

Plugin Registration

1. Add it to your agent's character configuration:

   {
     "name": "MyAgent",
     "plugins": [
       "@elizaos/plugin-example"
     ]
   }

2. Include it in your package.json:

   {
     "dependencies": {
       "@elizaos/plugin-example": "github:elizaos-plugins/plugin-example"
     }
   }

Creating a New Plugin

1. Use the plugin template as a starting point
2. Implement the Plugin interface:

   interface Plugin {
     actions?: Action[];
     evaluators?: Evaluator[];
     services?: Service[];
     providers?: Provider[];
     initialize?(runtime: AgentRuntime): Promise<void>;
   }

3. Create a plugin.json file with metadata and configuration schema
4. Document your plugin's functionality and required environment variables

Plugin Development Guidelines

1. Minimal Dependencies: Only include necessary dependencies
2. Clear Documentation: Document all required environment variables
3. Error Handling: Gracefully handle missing or invalid configuration
4. Type Safety: Use TypeScript for better developer experience
5. Testing: Include tests for core functionality

Visit the Plugin Development Guide for detailed information on creating new plugins.

Plugin Branding and Images

To maintain a consistent and professional appearance across the ElizaOS ecosystem, we recommend including the following assets in your plugin repository:

1. Required Images:

   • logo.png (400x400px) - Your plugin's square logo
   • banner.png (1280x640px) - A banner image for your plugin
   • screenshot.png - At least one screenshot demonstrating your plugin's functionality

2. Image Location:

   plugin-name/
   ├── assets/
   │   ├── logo.png
   │   ├── banner.png
   │   └── screenshots/
   │       ├── screenshot1.png
   │       └── screenshot2.png
   

3. README Integration:

   # My Amazing Plugin
   
   <div align="center">
     <img src="assets/banner.png" alt="Plugin Banner" width="100%">
   </div>
   
   ## Screenshots
   
   <div align="center">
     <img src="assets/screenshots/screenshot1.png" alt="Feature Demo" width="80%">
   </div>

4. Image Guidelines:

   • Use clear, high-resolution images
   • Keep file sizes optimized (< 500KB for logos, < 1MB for banners)
   • Follow the ElizaOS Brand Guidelines
   • Include alt text for accessibility

Example banner and logo placement:

💡 Pro Tip: Use the ElizaOS Plugin Banner Generator to create beautiful, consistent banners for your plugins.