Skip to main content

Eliza Plugin Development Guide

Overview​

Plugins are a powerful way to extend the functionality of your Eliza AI agents. This guide will walk you through the process of how to create custom plugins that can enhance your agent's capabilities, from simple utilities to complex integrations with external services. You'll learn how to leverage the plugin system to create modular and reusable components for your AI agents.

Learning Objectives​

After you complete this tutorial, you will be able to:

  • Create a new plugin repository from the template.
  • Understand the plugin development workflow.
  • Implement custom actions and services.
  • Integrate plugins with your Eliza agent.
  • Register and publish plugins to the Eliza Plugin Registry.
  • Use dependency injection for better plugin architecture.

Prerequisites​

Before you get started with Eliza, make sure you have:

Note for Windows Users: WSL 2 is required.

Quickstart​

Follow the Quickstart Guide to set up your development environment.

Plugin Development​

Create a Plugin repository from Template​

Visit Eliza Plugin Template and click "Use this template" to create a new repository.

Or, you can create a new empty repository and copy the files from some examples at the Eliza Plugins organization.

note

Flow's Eliza plugin template uses Dependency Injection(@elizaos-plugins/plugin-di). You can learn more about the Dependency Injection in the plugin's README.md. It allows you can use Class instead of Object for your Actions, Providers, Services, and so on. If you don't want to use it, you can follow the other examples in Eliza Plugins organiazation.

Add the Plugin repository to your Eliza project​

Let's say you created a repository named username/plugin-foo.

Use submodules to add the plugin repository to your Eliza project.


_10
git submodule add https://github.com/username/plugin-foo.git packages/plugin-foo

Change the package's name in the plugin's package.json to @elizaos-plugins/plugin-foo.


_10
{
_10
"name": "@elizaos-plugins/plugin-foo",
_10
}

Add the plugin to agent's package.json


_10
pnpm add @elizaos-plugins/plugin-foo@'workspace:*' --filter ./agent

Check the agent/package.json to make sure the plugin is added. You'll see something like this:


_10
{
_10
"dependencies": {
_10
"@elizaos-plugins/plugin-foo": "workspace:*"
_10
}
_10
}

Build the Plugin​

Build the plugin with the following command:


_10
pnpm build --filter ./packages/plugin-foo
_10
_10
# Or build all packages
_10
pnpm build

Add Plugin to the character.json you want to use​

Let's say you want to add the plugin to the sample character which is characters/sample.character.json.


_10
{
_10
"name": "Sample",
_10
"plugins": [
_10
"@elizaos-plugins/plugin-foo"
_10
]
_10
}

warning

If you use Dependency Injection(@elizaos-plugins/plugin-di) in your plugin, remember to add it to the postProcessors field. And clients field is deprecated in the latest version of Eliza, so if you want to add clients, you also need to use plugins field.


_10
{
_10
"name": "Sample",
_10
"plugins": [
_10
"@elizaos-plugins/plugin-foo",
_10
"@elizaos-plugins/client-discord"
_10
],
_10
"postProcessors": [
_10
"@elizaos-plugins/plugin-di"
_10
]
_10
}

Run the Eliza Agent with your Plugin​

Run the Eliza agent to test the plugin.


_10
pnpm start --character="characters/sample.character.json"
_10
_10
# Or with more debug logs
_10
pnpm start:debug --character="characters/sample.character.json"

Interact with the Agent​

Now, you're ready to start a conversation with your agent.

Open a new terminal window and run the client's http server.


_10
pnpm start:client

Plugin Registration​

You need to register your plugin in the Eliza Plugin Registry to make it available for other users.

Follow the guide there, modify the index.json file, and submit a pull request (PR) to the registry repository.

Conclusion​

In this tutorial, you've learned how to develop custom plugins for Eliza. You've gained experience with creating plugin repositories, implementing custom actions and services, integrating plugins with agents, and using dependency injection for better architecture.

Eliza's plugin system provides a powerful way to extend the functionality of your AI agents. With the knowledge gained from this tutorial, you can now develop more sophisticated plugins, create reusable components, and share your work through the plugin registry.

Rate this page