elizaos--eliza/packages/docs/plugins/create-a-plugin.md

title, sidebarTitle, description

title	sidebarTitle	description
Create a Plugin	Create a Plugin	Step-by-step tutorial for building a Eliza plugin from scratch — scaffolding, actions, providers, testing, and local development.

This tutorial walks you through creating a complete plugin from scratch. By the end you will have a working plugin with an action, a provider, and a background service running inside the Eliza runtime.

Prerequisites

• Node.js 22 or later
• A working Eliza installation (eliza start runs without errors)

Step 1: Scaffold the Project

Create the directory structure:

my-plugin/
├── package.json
├── tsconfig.json
└── src/
    └── index.ts

package.json

{
  "name": "@elizaos/plugin-my-feature",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "test": "vitest run"
  },
  "dependencies": {
    "@elizaos/core": "^2.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vitest": "^4.0.0"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "declaration": true,
    "strict": true
  },
  "include": ["src"]
}

Step 2: Implement an Action

Actions are things the agent can do. The LLM selects actions from the registered list based on description and examples.

// src/actions/weather.ts
import type { Action } from "@elizaos/core";

export const checkWeatherAction: Action = {
  name: "CHECK_WEATHER",
  description: "Check the current weather for a city",
  similes: ["GET_WEATHER", "WEATHER_LOOKUP", "FORECAST"],

  validate: async (_runtime, _message, _state) => {
    // Return false if the required API key is missing
    return Boolean(process.env.WEATHER_API_KEY);
  },

  handler: async (_runtime, _message, _state, options, _callback) => {
    const params = options?.parameters as Record<string, unknown> | undefined;
    const city = typeof params?.city === "string" ? params.city : "London";

    try {
      const url = `https://api.example-weather.com/current?city=${encodeURIComponent(city)}&key=${process.env.WEATHER_API_KEY}`;
      const res = await fetch(url);
      const data = await res.json() as { temp: number; condition: string };

      return {
        success: true,
        text: `Weather in ${city}: ${data.temp}°C, ${data.condition}`,
        data: { city, temp: data.temp, condition: data.condition },
      };
    } catch (err) {
      return {
        success: false,
        error: `Failed to fetch weather: ${err instanceof Error ? err.message : String(err)}`,
      };
    }
  },

  parameters: [
    {
      name: "city",
      description: "The city to check weather for",
      required: false,
      schema: { type: "string" },
    },
  ],

  examples: [
    [
      { user: "user", content: { text: "What's the weather in Tokyo?" } },
      { user: "assistant", content: { text: "Weather in Tokyo: 22°C, Partly cloudy", action: "CHECK_WEATHER" } },
    ],
  ],
};

Step 3: Implement a Provider

Providers inject context into the agent's prompt before each LLM inference. Unlike actions, they run automatically.

// src/providers/status.ts
import type { Provider } from "@elizaos/core";

export const pluginStatusProvider: Provider = {
  name: "weatherPluginStatus",
  description: "Provides current plugin status and configuration",
  position: 10, // Run after core providers

  get: async (_runtime, _message, _state) => {
    const hasApiKey = Boolean(process.env.WEATHER_API_KEY);

    return {
      text: hasApiKey
        ? "Weather plugin is active. You can check weather for any city."
        : "Weather plugin is configured but missing WEATHER_API_KEY.",
      values: {
        weatherPluginActive: hasApiKey,
      },
    };
  },
};

Step 4: Implement a Service

Services are long-running background processes that start with the runtime.

// src/services/weather-cache.ts
import type { IAgentRuntime, Service } from "@elizaos/core";

let cacheInterval: NodeJS.Timeout | undefined;
const weatherCache = new Map<string, { temp: number; condition: string; fetchedAt: number }>();

export const WeatherCacheService = {
  serviceType: "weather_cache",

  start: async (_runtime: IAgentRuntime): Promise<Service> => {
    // Refresh cache every 10 minutes
    cacheInterval = setInterval(() => {
      const now = Date.now();
      for (const [city, entry] of weatherCache) {
        if (now - entry.fetchedAt > 10 * 60 * 1000) {
          weatherCache.delete(city);
        }
      }
    }, 60_000);

    return {
      stop: async () => {
        if (cacheInterval) clearInterval(cacheInterval);
        weatherCache.clear();
      },
    } as Service;
  },
};

Step 5: Assemble the Plugin

// src/index.ts
import type { Plugin } from "@elizaos/core";
import { checkWeatherAction } from "./actions/weather";
import { pluginStatusProvider } from "./providers/status";
import { WeatherCacheService } from "./services/weather-cache";

const weatherPlugin: Plugin = {
  name: "weather-plugin",
  description: "Provides real-time weather information for any city",
  priority: 10,

  init: async (_config, runtime) => {
    runtime.logger?.info("[weather-plugin] Initialized");
    if (!process.env.WEATHER_API_KEY) {
      runtime.logger?.warn("[weather-plugin] WEATHER_API_KEY not set — CHECK_WEATHER action will be disabled");
    }
  },

  actions: [checkWeatherAction],
  providers: [pluginStatusProvider],
  services: [WeatherCacheService],
};

export default weatherPlugin;

This is a minimal plugin. The Plugin interface also supports evaluators, routes, events, models, componentTypes, and tests. See Plugin Schemas for all available extension points.

Step 6: Write Tests

// src/index.test.ts
import { describe, it, expect } from "vitest";
import {
  AgentRuntime,
  createCharacter,
  createMessageMemory,
  InMemoryDatabaseAdapter,
  stringToUuid,
  type IAgentRuntime,
  type Memory,
} from "@elizaos/core";
import weatherPlugin from "./index";

function createRuntime(): IAgentRuntime {
  return new AgentRuntime({
    agentId: stringToUuid("weather-test-agent"),
    character: createCharacter({ name: "Weather Test" }),
    adapter: new InMemoryDatabaseAdapter(),
    plugins: [],
    logLevel: "error",
  });
}

const mockMessage: Memory = createMessageMemory({
  entityId: stringToUuid("weather-test-user"),
  roomId: stringToUuid("weather-test-room"),
  content: { text: "What is the weather in Paris?" },
});

describe("weather-plugin", () => {
  it("exports a valid plugin", () => {
    expect(weatherPlugin.name).toBe("weather-plugin");
    expect(weatherPlugin.actions).toHaveLength(1);
    expect(weatherPlugin.providers).toHaveLength(1);
  });

  it("CHECK_WEATHER action fails validation without API key", async () => {
    delete process.env.WEATHER_API_KEY;
    const action = weatherPlugin.actions![0];
    const valid = await action.validate(createRuntime(), mockMessage);
    expect(valid).toBe(false);
  });

  it("CHECK_WEATHER action passes validation with API key", async () => {
    process.env.WEATHER_API_KEY = "test-key";
    const action = weatherPlugin.actions![0];
    const valid = await action.validate(createRuntime(), mockMessage);
    expect(valid).toBe(true);
    delete process.env.WEATHER_API_KEY;
  });
});

Step 7: Register with Runtime

Option	Best for	How it works
A: Local Plugin	Active development and testing	Auto-discovered from the project's plugins/ directory
B: Config-Based	Persistent installations with explicit control	Referenced by path in eliza.json
C: Character File	Per-agent plugin sets	Listed in the character definition, loaded at agent start

Option A: Local Plugin (Development)

Place the plugin directory inside the project:

eliza-project/
└── plugins/
    └── weather-plugin/
        ├── package.json
        └── src/index.ts

Eliza automatically discovers plugins in the plugins/ directory.

Option B: Config-Based Loading

Add to eliza.json:

{
  "plugins": {
    "allow": ["weather-plugin"],
    "entries": {
      "weather-plugin": {
        "path": "./plugins/weather-plugin"
      }
    }
  }
}

Option C: Character File

{
  "name": "MyAgent",
  "plugins": ["./plugins/weather-plugin"],
  "settings": {
    "secrets": {
      "WEATHER_API_KEY": "your-key-here"
    }
  }
}

Step 8: Build and Test

# Build the plugin
cd my-plugin && bun run build

# Run tests
bun test

# Start Eliza with the plugin loaded
eliza start

Check the logs for [weather-plugin] Initialized to confirm the plugin loaded.

Plugin Manifest (elizaos.plugin.json)

Every published plugin should include an elizaos.plugin.json manifest at its package root. This file tells the runtime and admin UI how to configure and display your plugin.

{
  "id": "plugin-weather",
  "name": "Weather Plugin",
  "version": "1.0.0",
  "kind": "feature",
  "description": "Provides real-time weather data to your agent",
  "configSchema": {
    "type": "object",
    "properties": {
      "apiKey": {
        "type": "string",
        "description": "OpenWeatherMap API key"
      },
      "units": {
        "type": "string",
        "enum": ["metric", "imperial"],
        "default": "metric"
      }
    },
    "required": ["apiKey"]
  },
  "uiHints": {
    "apiKey": {
      "label": "API Key",
      "type": "password",
      "help": "Get one at openweathermap.org/appid"
    },
    "units": {
      "label": "Temperature Units",
      "type": "select",
      "advanced": false
    }
  },
  "requiredSecrets": ["WEATHER_API_KEY"],
  "channels": ["chat", "telegram", "discord"],
  "dependencies": ["knowledge"]
}

Manifest Fields

Field	Type	Description
id	string	Unique plugin identifier (kebab-case)
name	string	Human-readable display name
version	string	Semver version
kind	PluginKind	One of: feature, ai-provider, connector, database, app, memory, channel, provider, skill
configSchema	JsonSchema	JSON Schema for plugin configuration
uiHints	Record<string, PluginConfigUiHint>	Hints for admin panel rendering, keyed by config property name
requiredSecrets	string[]	Environment variables that must be set
channels	string[]	Supported communication channels
dependencies	string[]	Other plugins this depends on

Additional fields like optionalSecrets, providers, skills, gatewayMethods, and cliCommands are also supported. See Plugin Schemas for the complete manifest reference.

UI Hints

The uiHints object controls how config fields appear in the admin dashboard. Each key matches a property name in configSchema:

interface PluginConfigUiHint {
  label: string;      // display label
  type: 'text' | 'password' | 'number' | 'select' | 'toggle' | 'textarea';
  help?: string;      // tooltip or helper text
  sensitive?: boolean; // if true, value is masked in the UI
  advanced?: boolean; // if true, hidden under "Advanced" toggle
}

---

How Plugin Discovery Works

When Eliza starts, it discovers plugins from multiple sources in this order:

1. Eliza plugin — Built-in workspace context and session management
2. Core plugins — Always loaded (@elizaos/plugin-sql, @elizaos/plugin-local-inference, etc.)
3. Connector plugins — Auto-enabled when channel config exists (e.g., telegram config → @elizaos/plugin-telegram)
4. Provider plugins — Auto-enabled when API key env var is set (e.g., ANTHROPIC_API_KEY → @elizaos/plugin-anthropic)
5. Feature plugins — Enabled via feature flags in eliza.json (e.g., features.browser: true → @elizaos/plugin-browser)
6. Ejected plugins — Git-cloned upstream plugins in ~/.local/state/eliza/plugins/ejected/ (take priority over npm versions)
7. User-installed plugins — Installed via bun add <name> (after editing character.plugins)
8. Custom plugins — Dropped into ~/.local/state/eliza/plugins/custom/

Auto-Enable by Environment Variable

Set an API key and the corresponding plugin loads automatically:

Environment Variable	Plugin
ANTHROPIC_API_KEY	@elizaos/plugin-anthropic
OPENAI_API_KEY	@elizaos/plugin-openai
GOOGLE_GENERATIVE_AI_API_KEY	@elizaos/plugin-google-genai
GROQ_API_KEY	@elizaos/plugin-groq
OPENROUTER_API_KEY	@elizaos/plugin-openrouter

Auto-Enable by Connector Config

Configure a channel in eliza.json and the connector plugin loads:

{
  "connectors": {
    "telegram": { "botToken": "..." },
    "discord": { "token": "..." }
  }
}

This auto-loads @elizaos/plugin-telegram and @elizaos/plugin-discord.

Disabling Auto-Enabled Plugins

Override in eliza.json:

{
  "plugins": {
    "entries": {
      "telegram": { "enabled": false }
    }
  }
}

---

Starter Template

If you have the upstream elizaos CLI installed globally, you can scaffold a plugin project:

# Requires the elizaos CLI (npm i -g elizaos@beta)
npx elizaos@beta create my-plugin --template plugin --language typescript

Alternatively, copy the manual scaffold from Step 1 above — it produces the same structure.

The template includes:

• Pre-configured package.json with @elizaos/core peer dependency
• TypeScript config targeting ES2022
• Example action, provider, and service
• Vitest test setup with runtime mocks
• elizaos.plugin.json manifest

---

Next Steps

• Testing Guide — Unit, integration, and E2E testing patterns
• Decision Guide — Choosing between Actions, Providers, Services, and Skills
• Plugin Patterns — Common patterns for services, state, and error handling
• Plugin Schemas — Full schema reference for all plugin types
• Publish a Plugin — Publish to the npm registry