Eliza Agent Framework

A comprehensive framework for building AI agents with persistent personalities across multiple platforms. ElizaOS provides the architecture, tools, and systems needed to create sophisticated agents.

Take a minute to review the following organizational chart:

Overview​

How ElizaOS Works​

When a user message is received:

1. Service Reception: Platform service (Discord, Telegram, etc.) receives the message

2. Runtime Processing: Agent runtime coordinates the response generation

3. Context Building: Providers supply relevant context (time, recent messages, knowledge)

4. Action Selection: The agent evaluates and selects appropriate actions

5. Response Generation: The chosen action generates a response

6. Learning & Reflection: Evaluators analyze the conversation for insights and learning

7. Memory Storage: New information is stored in the database

8. Response Delivery: The response is sent back through the service

This creates a continuous cycle of interaction, reflection, and improvement that allows agents to maintain consistent personalities while adapting to new information.

The AgentRuntime class is the primary implementation of the IAgentRuntime interface, which manages the agent's core functions, including:

Component	Description	API Reference	Related Files
Services	Supports multiple communication platforms and specialized functionalities for seamless interaction.	Services API	service.ts, Discord, Telegram, Twitter, Farcaster, Lens, Slack, Auto, GitHub
State	Maintains context for coherent cross-platform interactions, updates dynamically. Also tracks goals, knowledge, and recent interactions	State API	state.ts
Plugins	Dynamic extensions of agent functionalities using custom actions, evaluators, providers, and adapters	Plugins API	plugins.ts, actions, evaluators, providers
Services	Connects with external services for IMAGE_DESCRIPTION, TRANSCRIPTION, TEXT_GENERATION, SPEECH_GENERATION, VIDEO, PDF, BROWSER, WEB_SEARCH, EMAIL_AUTOMATION, and more	Services API	services.ts
Memory Systems	Creates, retrieves, and embeds memories and manages conversation history.	Memory API	memory.ts
Database Adapters	Persistent storage and retrieval for memories and knowledge	databaseAdapter	MongoDB, PostgreSQL, SQLite, Supabase, PGLite, Qdrant, SQL.js
Cache Management	Provides flexible storage and retrieval via various caching methods.	Cache API	cache.ts

Advanced: IAgentRuntime Interface

---

Key Methods​

• initialize(): Sets up the agent's runtime environment, including services, plugins, and knowledge processing.

• processActions(): Executes actions based on message content and state.

• evaluate(): Assesses messages and state using registered evaluators.

• composeState(): Constructs the agent's state object for response generation.

• registerService(): Adds a service to the runtime.

• getService(): Retrieves a registered service by type.

• useModel(): Utilizes AI models with typesafe parameters and results.

• ensureRoomExists() / ensureConnection(): Ensures the existence of communication channels and connections.

Service System​

Services provide specialized functionality with standardized interfaces that can be accessed cross-platform:

// Speech Generation
const speechService = runtime.getService<ISpeechService>('speech_generation');
const audioStream = await speechService.process(text);

// PDF Processing
const pdfService = runtime.getService<IPdfService>('pdf');
const textContent = await pdfService.convertPdfToText(pdfBuffer);

// Discord Integration
const discordService = runtime.getService<IDiscordService>('discord');
await discordService.sendMessage(channelId, content);

---

State Management​

The runtime maintains comprehensive state through the State interface:

interface State {
  // Core state data
  values: {
    [key: string]: any;
  };
  data: {
    [key: string]: any;
  };
  text: string;
}

// State composition example
async function manageState() {
  // Initial state composition with all regular providers
  const state = await runtime.composeState(message);

  // State with specific providers only
  const filteredState = await runtime.composeState(message, ['timeProvider', 'recentMessages']);

  // Include private or dynamic providers
  const enhancedState = await runtime.composeState(message, null, [
    'weatherProvider',
    'portfolioProvider',
  ]);
}

---

Plugin System​

Plugins extend agent functionality through a modular interface. The runtime supports various types of plugins including services, adapters, actions, and more:

interface Plugin {
  name: string;
  description: string;
  init?: (config: Record<string, string>, runtime: IAgentRuntime) => Promise<void>;

  // Components
  services?: (typeof Service)[]; // Communication platforms and external integrations
  actions?: Action[]; // Custom behaviors
  providers?: Provider[]; // Data providers
  evaluators?: Evaluator[]; // Response assessment
  adapters?: Adapter[]; // Database/cache adapters
  routes?: Route[]; // API endpoints
  tests?: TestSuite[]; // Testing utilities
}

Plugins can be configured through characterfile settings:

{
  "name": "MyAgent",
  "plugins": ["@elizaos/plugin-solana", "@elizaos/plugin-twitter"],
  "settings": {
    "twitter": {
      "shouldRespondToMentions": true
    },
    "solana": {
      "enableAutoTrading": false
    }
  }
}

For detailed information about plugin development and usage, see the ElizaOS Registry.