Building an Onchain AI Agent with RAG and Memory

The convergence of artificial intelligence and blockchain technology is opening new frontiers for autonomous agents capable of onchain interaction. In this article, we will walk through building a conversational AI agent that interfaces with smart contracts on the Metis Hyperion Testnet. This project integrates memory, retrieval-augmented generation (RAG), and Web3 functionality using the Alith framework.

This agent not only queries ERC20 token balances and metadata but also remembers past user interactions and retrieves contextual knowledge from a local store. By leveraging the Alith framework alongside Web3.py and vector databases, developers can create intelligent agents with both domain knowledge and transactional capabilities.

Overview of Features

This Onchain AI Agent includes the following capabilities:

• ERC20 Token Balance Checker: Fetches balance and metadata for any ERC20 token on Metis Hyperion.
  
  
• Memory-Enabled Conversations: Maintains a persistent memory of previous user inputs for contextual responses.
  
  
• Knowledge Base via RAG: Retrieves information from a local knowledge repository, including details about Metis, token standards, and best practices.
  
  
• Alith Integration: Connects a natural language interface to blockchain agents via OpenAI-compatible models.
  
  

Getting Started

To begin, clone the repository and set up your Python environment:

git clone https://github.com/metis-edu/Onchain-Agent-RAG-with-Memory.git

cd Onchain-Agent-RAG-with-Memory

python -m venv venv

source venv/bin/activate  # On Windows, use: venv\Scripts\activate

pip install alith web3 python-dotenv torch

For vector-based semantic search functionality, install the following:

pip install "pymilvus[model]"

Environment Configuration

Create a .env file in the root directory and include your OpenAI API key:

API_KEY=your_openai_api_key

This key is required for the Alith agent to access language model capabilities.

Running the Agent

Start the agent with:

python demo.py

The interface supports command-line input. For example, to check the balance of a token for a specific wallet, use:

check <token_contract_address> <wallet_address>

Example Output

Token Balance Report

Token Name: ExampleToken

Symbol: EXT

Total Supply: 1,000,000.00 EXT

Decimals: 18

Wallet: 0x412dA7...F5063

Balance: 250.00 EXT

Raw Balance: 250000000000000000000

‍

System Architecture

The agent combines several components:

• Web3.py: Interfaces with the Ethereum-compatible Metis Hyperion network for smart contract interactions.
  
  
• Alith.Agent: Handles conversational logic, memory persistence, and prompt orchestration.
  
  
• dotenv: Loads environment variables securely.
  
  
• MilvusStore (optional): Acts as a vector database for retrieval-augmented generation from a local markdown knowledge base.
  
  
• metis_knowledge.md: Contains domain-specific information on Metis, tokens, and best practices.
  
  

Use Cases

This agent is suitable for developers and power users who require:

• Real-time token balance verification
  
  
• Context-aware blockchain queries
  
  
• AI-powered assistance for smart contract interaction
  
  
• Automated Telegram bot deployments
  
  

The included tg-bot.py script demonstrates how the agent can be deployed as a Telegram bot to facilitate:

• Token deployment (ERC20, ERC721, ERC1155)
  
  
• Natural language queries about balances and metadata
  
  
• Simplified user interaction for onchain operations
  
  

Troubleshooting

Issue

Solution

Missing API key error

Ensure .env is present and API_KEY is defined

No token data returned

Verify the contract address is valid and deployed on Metis Sepolia

RAG not working

Ensure Milvus is installed and properly configured

Agent unresponsive

Check Metis Sepolia RPC endpoint and network connectivity

Resources

• Metis Hyperion Explorer 
• OpenAI API Documentation
  
  
• Alith Framework Repository 
• Python Telegram Bot Documentation
  
  

Conclusion

The integration of AI with blockchain offers powerful possibilities for creating intelligent agents that are both conversational and transactional. With memory and retrieval capabilities, these agents become valuable tools for interacting with smart contracts in a user-friendly and efficient manner.

By leveraging the Alith framework on Metis Hyperion, developers can rapidly prototype and deploy advanced onchain AI agents with real-world applications ranging from token management to autonomous decentralized operations.

For more information and source code, refer to the official GitHub repository.

‍