elizaos-plugin-guide

ElizaOS Plugin Development Guide

ElizaOS is the leading framework for autonomous AI agents in Web3. This guide covers plugin development, architecture, and DeFi integration patterns.

ElizaOS Architecture

ElizaOS Runtime
├── Core
│   ├── Memory Manager     # Persistent conversation memory
│   ├── Action System      # Tool execution
│   ├── Evaluator System   # Response quality evaluation
│   └── Provider System    # Context injection
├── Plugins
│   ├── @elizaos/plugin-solana    # Solana tools
│   ├── @elizaos/plugin-evm       # EVM chain tools
│   ├── @elizaos/plugin-twitter   # X/Twitter integration
│   └── Your custom plugin        # ← This guide
└── Clients
    ├── Discord
    ├── Telegram
    ├── Twitter/X
    └── Direct (REST API)

Plugin Structure

my-eliza-plugin/
├── src/
│   ├── index.ts          # Plugin entry point
│   ├── actions/          # Actions (tools) the agent can execute
│   │   ├── swap.ts
│   │   └── portfolio.ts
│   ├── evaluators/       # Evaluate responses and context
│   │   └── riskCheck.ts
│   ├── providers/        # Inject context into prompts
│   │   └── priceData.ts
│   └── types.ts          # TypeScript types
├── package.json
└── tsconfig.json

Entry Point

import { Plugin } from '@elizaos/core';
import { swapAction } from './actions/swap';
import { portfolioAction } from './actions/portfolio';
import { riskEvaluator } from './evaluators/riskCheck';
import { priceProvider } from './providers/priceData';

export const speraxPlugin: Plugin = {
  name: 'sperax',
  description: 'Sperax DeFi tools — USDs yield, SPA staking, Farms',
  actions: [swapAction, portfolioAction],
  evaluators: [riskEvaluator],
  providers: [priceProvider],
};

export default speraxPlugin;

Actions (Tools)

Actions are things the agent can do:

import { Action, IAgentRuntime, Memory } from '@elizaos/core';

export const swapAction: Action = {
  name: 'SWAP_TOKENS',
  description: 'Swap tokens on a DEX',
  
  // Determines if this action should be triggered
  validate: async (runtime: IAgentRuntime, message: Memory) => {
    return message.content.text.toLowerCase().includes('swap');
  },
  
  // Executes the action
  handler: async (runtime: IAgentRuntime, message: Memory) => {
    const { tokenIn, tokenOut, amount } = parseSwapIntent(message.content.text);
    
    // Execute swap via DEX aggregator
    const result = await executeSwap({
      tokenIn,
      tokenOut,
      amount,
      chain: 'arbitrum',
    });
    
    return {
      text: `Swapped ${amount} ${tokenIn} for ${result.amountOut} ${tokenOut}`,
      action: 'SWAP_TOKENS',
    };
  },
  
  // Example conversations for the LLM
  examples: [
    [
      { user: 'user1', content: { text: 'Swap 100 USDC for SPA' } },
      { user: 'agent', content: { text: 'Swapping 100 USDC for SPA on Arbitrum...' } },
    ],
  ],
};