Reading Notes of ElizaOS [1]

4 min readJan 25, 2025

(Jan 2025)

This is the first part of my reading notes when developing a new AI agent using ElizaOS. See part 2 here.

0-Executive Summary

This document contains short working notes when studying the AI Agent creation framework named ElizaOS. Its agents can call on blockchain transactions.

This open-source framework in TypeScript has been released by the DAO (Decentralized Anonymous Organization) named ai16z, on September 2024. Its github repository has already received more than 14.000 stars beginning January 2025, much faster than any other AI agent frameworks.

The name ElizaOS hints that one can use Eliza framework building blocks to create AI Agents and then execute them in the ElizaOS runtime environment.

The current exploration paper is done in the context of the project Machu Picchu, that uses 21st century tools for humanitarian purposes : https://kvutien-yes.medium.com/project-machu-picchu-white-paper-2024-part-1-735b60c55a92

0.1- Reminder: what is an agent?

In its simplest form, which is also the most common usage, an AI agent is (1) a Finite State Machine (2) that uses Artificial Intelligence to “understand” events triggering its state transitions. A Finite State Machine can be implemented using simple electrical relays, using no programming. AI-powered agents is the next state beyond “dumb” Finite State Machines.

The diagrams below shows an agent in general and an example of state machine controlling a turnstile door.

0.2- Reminder: potential evolution of AI Agents in the future

The next step of AI agents is often presented as AGI (Artificial General Intelligence) and ASI (Artificial Superior Intelligence). These are marketing names to designate broadly State Machines that remember previous transitions, evaluate past results and compare with a goal, eventually change the evaluation functions used to reach the goal or even decide to change intermediate goals (the transition table) to fulfill a larger planning strategy. In short, they would replace humans and be better in executing their mission.

Such machines are far from being convincingly achieved. However, Eliza is one step forward towards AGI.

1- Eliza High Level Architecture and Workflow

1.1- Eliza major functional blocks

The following drawing, taken from Eliza documentation, shows the major functional blocks of Eliza.

1.2- Eliza Execution Workflow

The following workflow is deducted from reading the code of Eliza. It may contain inaccuracies and will be modified if appropriate.

the Runtime initializes the agent and manages state transitions
the Agent uses Provider clients to detect events, uses AI to match the event with what is programmed in its transition table (matching = “understand” the event), updates the memory database, evaluates and launches the appropriate Actions,
the Actions eventually interact with the external world using Provider clients.

2-Components of Eliza

The following description of components is deducted from reading the code of Eliza. It may contain inaccuracies and will be modified if appropriate.

2.1- Classical Eliza State Machine Components

Agent runtime : watches Provider for external events, analyzes input, assesses response, triggers action, manages state transition
Provider : injects into Eliza external data and real-time information (events),
Action System : extensible system to customize the agent
Database Adapter : memorizes the state

2.2- IA Variants in Eliza of State Machine Components

Database Adapter : additional function to memorize the previous AI embeddings, i.e. vector representations of the previous events, inputs, responses and response evaluations
Character System : personality management. JSON-formatted data to define an AI behavior. Similar to system prompts in a chatbot, serves to the IA model to analyze inputs, generate outputs (state transition and action) and evaluate goal adequation
Provider Client : interface to social media like Telegram, X/Twitter, or custom external systems
Model Provider : defines the IA model to use to infer answers from events (GPT, Claude, Mistral, Llama, DeepSeek, Qwen, Phi-4 etc.)
Vector database : stores embeddings of character, inputs, past responses, past states etc.
Boredom Provider : calculates the level of boredom of an agent to modulate responses
Conversation Flow : evaluate the appropriateness of actions, modulates responses like ignore input or even terminate conversation
Evaluator : determines appropriateness of input, responses with respect to goal and internal ethics

2.3- Eliza Specific Components

Plugins : extensions to Agent {Evaluator, Action, Character}.
For example, image generator, NodeJS services, manage temporal context, assess factual accuracy of message content, blockchain access, wallet management, DeFi trader, mass payments, fungible and non-fungible tokens, TEE cybersecurity execution environment, webhooks to blockchain events etc.

2.4-Eliza Package Dependencies

3- Development using Eliza Framework

If you don’t intend to customize an agent using Eliza, you can stop reading here. Else, read Part 2.

Originally published at https://www.linkedin.com.