Skip to main content

Quickstart Guide to build AI Agent on Flow with Eliza

Overview​

Eliza is a powerful framework for building AI agents that can interact with users through natural language. This tutorial will guide you through how to set up and deploy an AI agent on the Flow blockchain with Eliza. You'll learn how to create intelligent agents that can understand and respond to user queries, while leveraging Flow's secure and scalable infrastructure.

Learning Objectives​

After you complete this tutorial, you will be able to:

  • Set up the Eliza development environment.
  • Configure and deploy an AI agent on Flow.
  • Create and customize character configurations.
  • Integrate different AI models with your agent.
  • Interact with your AI agent through a web interface.
  • Add and develop custom plugins for extended functionality.

Prerequisites​

Before you get started started with Eliza, make sure you have:

Note for Windows Users: WSL 2 is required.

Installation​

ElizaOnFlow is a Flow-dedicated Eliza wrapper, so:

  • The plugins from this repository are also compatible with the origin Eliza.
  • You can also use any plugins from original Eliza in this repository.

Clone the repository


_10
# The ElizaOnFlow is a wrapper with origin Eliza as submodule
_10
git clone --recurse-submodules https://github.com/onflow/elizaOnFlow.git
_10
_10
# Enter directory
_10
cd elizaOnFlow
_10
_10
# Please checkout the main branch which is using the latest release of origin Eliza
_10
git checkout main

Or, If you want to use the origin Eliza, run:


_10
# Eliza's characters folder is a submodule
_10
git clone --recurse-submodules https://github.com/elizaOs/eliza.git
_10
_10
# Enter directory
_10
cd eliza
_10
_10
# Checkout the latest release
_10
git checkout $(git describe --tags --abbrev=0)

If you already cloned without submodules, run:


_10
# Fetch submodules
_10
git submodule update --init --recursive

Install dependencies


_10
pnpm install --no-frozen-lockfile

warning

Only use the --no-frozen-lockfile option when you're initially instantiating the repo or bump the version of a package or add a new package to your package.json file. This practice helps maintain consistency in your project's dependencies and prevents unintended changes to the lockfile.

If you use ElizaOnFlow, you need to install Flow Cadence contracts dependencies to ensure that the Cadence extension correctly lints *.cdc.

Install Flow Cadence contracts dependencies:


_10
flow deps install

Build all packages:


_10
pnpm build

Configure Environment​

Copy .env.example to .env and fill in the appropriate values.


_10
cp .env.example .env

danger

In normal development, it's a best practice to use a .env to protect API keys and other sensitive information. When you work with crypto, it's critical to always use them, even in test projects or tutorials. If you expose a wallet key, you might lose everything in that wallet immediately, or someone might watch it for years and rob you the day you put something valuable there.

Edit .env and add your values. Do NOT add this file to version control.

Choose Your Model​

Eliza supports multiple AI models and you set which model to use inside the character JSON file. But remember, after you chosed a model, you need to set up the relevant configuration.

Check the full list of supported LLMs in origin Eliza: Models.ts

Suggested models:

  • Use API to access LLM providers:
    • OpenAI: set modelProvider as openai, and set OPENAI_API_KEY in .env.
    • Deepseek: set modelProvider as deepseek, and set DEEPSEEK_API_KEY in .env.
    • Grok: set modelProvider as grok, and set GROK_API_KEY in .env.
  • Use local inference
    • Ollama: set modelProvider as ollama, and set OLLAMA_MODEL in .env to the model name you use in ollama.

To choose a model, you need to set in charactor configuration. For example: OPENAI, set modelProvider: "openai" in charactor JSON file or modelProvider: ModelProviderName.OPENAI in charactor.ts

Setup Agent's Flow Account​

Create a new Flow account for the Agent. Learn more: doc


_10
flow accounts create

If you use Testnet, you can get free tokens from Flow Faucet

Set the Flow blockchain configuration in .env with a newly-generated Flow account.


_10
FLOW_ADDRESS=
_10
FLOW_PRIVATE_KEY=
_10
FLOW_NETWORK= # Default: mainnet
_10
FLOW_ENDPOINT_URL= # Default: <https://mainnet.onflow.org>

For testnet, check Flow's Networks for more information.

Create Your First Agent​

Create a Character File​

View the deps/eliza/characters/ directory for a number of character files to try out. Additionally, you can edit charactor.ts to override Eliza's defaultCharacter file, which is the default character file used if no character json files are provided.

Copy one of the example character files and make it your own:


_10
cp characters/scooby.character.json characters/sample.character.json

📝 Character Documentation

Start the Agent​

Tell it which character you want to run:


_10
pnpm start --character="characters/sample.character.json"

Or, you can use pnpm start:debug for more debugging logs:


_10
pnpm start:debug --character="characters/sample.character.json"

You can load multiple characters with a comma-separated list:


_10
pnpm start --characters="characters/sample.character.json, characters/scooby.character.json"

Add / Develop Plugins​

Run npx elizaos plugins list to get a list of available plugins or visit Eliza Plugins Registry

Run npx elizaos plugins add @elizaos-plugins/plugin-NAME to install the plugin into your instance

To create a new plugin for your own business, refer to the plugin development guide.

Additional Requirements​

You may need to install Sharp. If you see an error when starting up, install it with the following command:


_10
pnpm install --include=optional sharp

Interact with the Agent​

Now you're ready to start a conversation with your agent.

Open a new terminal window and run the client's http server.


_10
pnpm start:client

After the client is running, you'll see a message like this:


_10
➜ Local: http://localhost:5173/

Click the link or open your browser to http://localhost:5173/. You'll see the chat interface connect to the system, and you can now interact with your character.

Common Issues & Solutions​

Check the orgin Eliza's Common Issues & Solutions

Conclusion​

In this tutorial, you've learned how to build and deploy an AI agent on the Flow blockchain using Eliza. You've gained hands-on experience with setting up the development environment, configuring agents, creating character configurations, integrating AI models, and developing custom plugins.

The Eliza framework provides a powerful way to create intelligent agents that can understand and respond to user queries while leveraging Flow's secure and scalable infrastructure. Now taht you've completed this tutorial, you now have the foundation to build more sophisticated AI agents and create unique user experiences through character customization and plugin development.

Rate this page