Components

const action: Action = {
  name: "MY_ACTION",
  description: "Does something",
  validate: async () => true,
  handler: async (runtime, message) => {
    return {
      success: true, // REQUIRED
      text: "Done!",
    };
  },
};

const sendTokenAction: Action = {
  name: "SEND_TOKEN",
  description: "Send tokens to address",

  validate: async (runtime, message) => {
    return message.content.includes("send") && message.content.includes("0x");
  },

  handler: async (runtime, message) => {
    const address = extractAddress(message.content);
    const amount = extractAmount(message.content);
    await sendToken(address, amount);
    return {
      success: true,
      text: `Sent ${amount} tokens to ${address}`,
    };
  },
};

const action: Action = {
  name: "WEATHER",
  description: "Get weather info",
  examples: [
    [
      { name: "user", content: { text: "What's the weather?" } },
      { name: "agent", content: { text: "Let me check the weather for you." } },
    ],
  ],
  validate: async (runtime, message) => {
    return message.content.toLowerCase().includes("weather");
  },
  handler: async (runtime, message) => {
    const weather = await fetchWeather();
    return {
      success: true,
      text: `It's ${weather.temp}°C and ${weather.condition}`,
    };
  },
};

// Using callbacks
handler: async (runtime, message, state, options, callback) => {
  const result = await doWork();
  if (callback) {
    await callback({ text: result }, []);
  }
  return { success: true, text: result };
};

// Using services
handler: async (runtime, message) => {
  const service = runtime.getService<XService>("x");
  return service.post(message.content);
};

// Using database
handler: async (runtime, message) => {
  const memories = await runtime.databaseAdapter.searchMemories({
    query: message.content,
    limit: 5,
  });
  return { success: true, data: { memories } };
};

interface HandlerOptions {
  /** Context with previous action results and utilities */
  actionContext?: ActionContext;

  /** Multi-step action plan information */
  actionPlan?: {
    totalSteps: number; // Total steps in plan
    currentStep: number; // Current step (1-based)
    steps: Array<{
      action: string;
      status: "pending" | "completed" | "failed";
      result?: ActionResult;
      error?: string;
    }>;
    thought: string; // AI's reasoning for this plan
  };

  /** Allow plugin extensions */
  [key: string]: unknown;
}

interface ActionContext {
  previousResults: ActionResult[];
  currentStep: number;
  totalSteps: number;
}

handler: async (runtime, message, state, options, callback) => {
  // Check if this is part of a multi-step plan
  if (options?.actionPlan) {
    const { currentStep, totalSteps, thought } = options.actionPlan;
    console.log(`Step ${currentStep}/${totalSteps}: ${thought}`);
  }

  // Access previous action results
  if (options?.actionContext?.previousResults) {
    const lastResult = options.actionContext.previousResults.at(-1);
    // Use data from previous step
  }

  return { success: true, text: "Done" };
};

const provider: Provider = {
  name: "MY_DATA",
  get: async (runtime, message, state) => {
    return {
      text: "Contextual information",
      data: { key: "value" },
    };
  },
};

const dynamicProvider: Provider = {
  name: "LIVE_DATA",
  dynamic: true, // Re-fetched each time
  get: async (runtime) => {
    const data = await fetchLatestData();
    return { data };
  },
};

const secretProvider: Provider = {
  name: "INTERNAL_STATE",
  private: true, // Not shown in provider list
  get: async (runtime) => {
    return runtime.getInternalState();
  },
};

// Lower numbers = higher priority
position: -100; // Loads first
position: 0; // Default
position: 100; // Loads last

flowchart TD
    Response[Agent Response] --> Validate[validate]
    Validate -->|true| Handler[handler]
    Validate -->|false| Skip[Skip]
    Handler --> Extract[Extract Info]
    Extract --> Store[Store in Memory]
    Store --> Continue[Continue]
    Skip --> Continue

    classDef input fill:#2196f3,color:#fff
    classDef decision fill:#ff9800,color:#fff
    classDef processing fill:#4caf50,color:#fff
    classDef storage fill:#9c27b0,color:#fff
    classDef result fill:#607d8b,color:#fff

    class Response input
    class Validate decision
    class Handler,Extract processing
    class Store storage
    class Skip,Continue result

const evaluator: Evaluator = {
  name: "my-evaluator",
  description: "Processes responses",
  examples: [], // Training examples

  validate: async (runtime, message) => {
    return true; // Run on all messages
  },

  handler: async (runtime, message) => {
    // Process and extract
    const result = await analyze(message);
    // Store findings
    await storeResult(result);
    return result;
  },
};

const evaluator: Evaluator = {
  name: "fact-extractor",
  description: "Extracts facts from conversations",
  examples: [
    {
      prompt: "Extract facts from this conversation",
      messages: [
        { name: "user", content: { text: "I live in NYC" } },
        { name: "agent", content: { text: "NYC is a great city!" } },
      ],
      outcome: "User lives in New York City",
    },
  ],
  validate: async () => true,
  handler: async (runtime, message, state) => {
    const facts = await extractFacts(state);
    for (const fact of facts) {
      await runtime.factsManager.addFact(fact);
    }
    return facts;
  },
};

import { Service, IAgentRuntime, logger } from "@elizaos/core";

// Define client interface for type safety
interface ServiceClient {
  connect(): Promise<void>;
  disconnect(): Promise<void>;
}

export class MyService extends Service {
  static serviceType = "my-service";
  capabilityDescription = "Description of what this service provides";

  private client: ServiceClient | null = null;
  private refreshInterval: NodeJS.Timer | null = null;

  constructor(protected runtime: IAgentRuntime) {
    super();
  }

  static async start(runtime: IAgentRuntime): Promise<MyService> {
    logger.info("Initializing MyService");
    const service = new MyService(runtime);

    // Initialize connections, clients, etc.
    await service.initialize();

    // Set up periodic tasks if needed
    service.refreshInterval = setInterval(
      () => service.refreshData(),
      60000, // 1 minute
    );

    return service;
  }

  async stop(): Promise<void> {
    // Cleanup resources
    if (this.refreshInterval) {
      clearInterval(this.refreshInterval);
    }
    // Close connections
    if (this.client) {
      await this.client.disconnect();
    }
    logger.info("MyService stopped");
  }

  private async initialize(): Promise<void> {
    // Service initialization logic
    const apiKey = this.runtime.getSetting("MY_API_KEY");
    if (!apiKey) {
      throw new Error("MY_API_KEY not configured");
    }

    this.client = new MyClient({ apiKey });
    await this.client.connect();
  }
}

export class MyService extends Service {
  static serviceType = "my-service";

  static async start(runtime: IAgentRuntime): Promise<MyService> {
    const service = new MyService(runtime);

    // Immediate initialization
    await service.initialize();

    // Delayed initialization for non-critical tasks
    setTimeout(async () => {
      try {
        await service.loadCachedData();
        await service.syncWithRemote();
        logger.info("MyService: Delayed initialization complete");
      } catch (error) {
        logger.error("MyService: Delayed init failed", error);
        // Don't throw - service is still functional
      }
    }, 5000);

    return service;
  }
}

// Providers contribute to state
const state = await runtime.composeState(message, [
  "RECENT_MESSAGES",
  "CHARACTER",
  "KNOWLEDGE",
]);

// Actions receive composed state
const result = await action.handler(runtime, message, state);

// Evaluators process with full context
await evaluator.handler(runtime, message, state);

// Actions and providers can access services
const service = runtime.getService<MyService>("my-service");
const data = await service.getData();

import type { Plugin } from "@elizaos/core";

export const myPlugin: Plugin = {
  name: "my-complete-plugin",
  description: "Example plugin with all component types",

  services: [MyService],

  actions: [
    {
      name: "MY_ACTION",
      description: "Performs an action using the service",
      validate: async (runtime) => {
        return runtime.getService("my-service") !== null;
      },
      handler: async (runtime, message) => {
        const service = runtime.getService<MyService>("my-service");
        const result = await service.doSomething();
        return { success: true, text: result };
      },
    },
  ],

  providers: [
    {
      name: "MY_PROVIDER",
      get: async (runtime) => {
        const service = runtime.getService<MyService>("my-service");
        const data = await service.getCurrentState();
        return {
          text: `Current state: ${JSON.stringify(data)}`,
          data,
        };
      },
    },
  ],

  evaluators: [
    {
      name: "MY_EVALUATOR",
      description: "Extracts relevant information",
      examples: [],
      validate: async () => true,
      handler: async (runtime, message) => {
        const extracted = await extractInfo(message);
        await runtime.storeExtracted(extracted);
        return extracted;
      },
    },
  ],
};