GitHub Discord X

Build a Dune Agent with SwarmZero.ai

Dune Analytics is a powerful platform for exploring and visualizing blockchain data. It allows users to write SQL queries to extract insights from blockchain transactions and smart contracts. The platform provides tools for creating custom dashboards and sharing data visualizations with others. It is widely used by analysts, developers, and researchers to track and analyze blockchain metrics and trends.

Imagine having an agent search for indexes and crypto narratives using the DUNE API, providing updated market data. With this Dune Agent, you can access detailed insights into the ALPHA, Beta, and Gamma Indexes, as well as Daily, Weekly, Monthly, and Quarterly Crypto Narratives. This offers comprehensive and timely information on the latest crypto trends, enabling you to make informed decisions and stay ahead in the crypto market.

This tutorial will guide you through setting up, configuring, and extending a Dune Analytics agent using the dune_agent repository from SwarmZero.ai.

Watch Our Demo here:

Prerequisites

Before starting, ensure you have the following:

  • Python 3.8 or higher installed

  • Git installed

  • An IDE or text editor (VS Code, PyCharm, etc.)

  • Basic understanding of Python programming

  • Dune Analytics account and API key

  • API keys from OpenAI, Anthropic, and Mistral if you plan to use these services

Step-By-Step Tutorial for Building a Dune Agent with SwarmZero.ai

Here is a detailed guide to building the Dune Agent:

Cloning the Repository

To begin, we need to clone the dune_agent repository to our local machine. This will give you access to the code and resources needed to run and customize the Dune Agent.

Step 1: Open your terminal or command prompt. Ensure you have Git installed on your system.

Step 2: Run the following commands: 

git clone https://github.com/hivenetwork-ai/example-agents/ 
cd dune_agent

These commands will download the repository and navigate into its directory, setting up the base environment to start working on the agent.

Setting Up the Environment

Now that you have the repository cloned, the next step is to set up the environment to run the agent. This involves creating a virtual environment, installing dependencies, and configuring environment variables.

Step 1: Create a virtual environment: 

python -m venv ./venv

Step 2: Activate the virtual environment

  • Command Prompt:

    venv\Scripts\activate.bat

  • PowerShell:

    venv\Scripts\Activate.ps1

  • On Unix/Mac:

    source venv/bin/activate

Installing Dependencies

With the virtual environment activated, install the required dependencies:

pip install -r requirements.txt

Setting Up Environment Variables

Step 1: Create a new file called .env in the root directory:

touch .env

Step 2: Copy the contents of .env.example into your new .env file.

Step 3: Add your API keys to the .env file:

DUNE_API_KEY=your_dune_api_key
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
MISTRAL_API_KEY=your_mistral_api_key

These steps will ensure your environment is properly configured to run the Dune Agent.

Understanding the Code Structure

Before running and customizing the agent, it's essential to understand the structure of the dune_agent repository. This will help you navigate through the code and make necessary modifications efficiently.

Overview of Key Files and Directories:

  • .env.example: This file provides an example of the environment variables required for the project. You should copy this file to create your .env file and add the necessary API keys.

  • hive_config.toml: Contains configuration settings for the agent, such as API keys, query parameters, and other adjustable settings. This file is essential for configuring the agent's behavior.

  • hive_crypto_agent.py: This is the main script that runs the agent. It contains the core logic for fetching data from Dune Analytics, processing it, and outputting results.

  • requirements.txt: Lists all the dependencies required to run the agent. These are the libraries and tools the agent relies on.

  • requirements-dev.txt: Lists the development dependencies needed for testing and development purposes. This file is useful for setting up a development environment.

Building the Dune Agent (hive_crypto_agent.py)

In this section, you will now understand the logic and the process of building an AI agent with SwarmZero.ai.

Step 1: Import Necessary Libraries

Start by importing all the required libraries. These include libraries for handling environment variables, making HTTP requests, logging, and interacting with the HiveAgent.

from hive_agent import HiveAgent
import os
from typing import Optional, Dict
import requests
import time
import logging
from dotenv import load_dotenv

Step 2: Load Environment Variables

Load your environment variables from a .env file. This file should contain your Dune API key, which will be used to authenticate your requests.

load_dotenv()
dunekey = os.getenv("DUNE_API_KEY")

Step 3: Configure Logging

Set up logging to help you monitor the execution of your program. This will output logs to the console, showing information such as API responses and errors.

logging.basicConfig(level=logging.INFO)

Step 4: Define the Utility Function to Get the Configuration Path

Define a utility function to get the absolute path to your configuration file. This helps in managing file paths across different environments.

def get_config_path(filename):
    return os.path.abspath(os.path.join(os.path.dirname(__file__), filename))

Step 5: Define Function to Execute Dune Queries

Create a function to execute queries on the Dune Analytics API. This function sends a POST request to the Dune API to initiate the execution of a query.

def execute_query(execute):
    headers = {"X-DUNE-API-KEY": dunekey}
    url = "https://api.dune.com/api/v1/query/{execute}/execute"
    try:
        response = requests.request(
            "POST", url.format(execute=execute), headers=headers
        )
        logging.info(response.text)
        return response
    except requests.exceptions.RequestException as e:
        logging.error(f"Error fetching data: {e}")

Step 6: Define the Function to Wait for Query Execution

This function checks the status of a query execution at regular intervals until it is complete or a maximum number of attempts is reached.

def wait_for_execution(execution_id, max_attempts=60, delay=5):
    url = "https://api.dune.com/api/v1/execution/{execution_id}/status"
    headers = {"X-DUNE-API-KEY": dunekey}
    attempts = 0
    while attempts < max_attempts:
        try:
            response = requests.request(
                "GET", url.format(execution_id=execution_id), headers=headers
            )
            logging.info(response.text)
        except requests.exceptions.RequestException as e:
            print(f"Error fetching data: {e}")
        if response is None:
            return None
        logging.info(f"Attempt {attempts + 1}: {response}")

        if response.json()["is_execution_finished"] == True:
            logging.info("Execution finished!")
            return response

        attempts += 1
        time.sleep(delay)

    logging.info(f"Execution did not finish after {max_attempts} attempts.")
    return None

Step 7: Define the Function to Fetch Query Results

After the query execution is complete, this function retrieves the results of the query from the Dune API.

def get_results(query_id):
    headers = {"X-DUNE-API-KEY": dunekey}
    url = "https://api.dune.com/api/v1/query/{query_id}/results"
    try:
        response = requests.request(
            "GET", url.format(query_id=query_id), headers=headers
        )
        logging.info(response.text)
        return response
    except requests.exceptions.RequestException as e:
        logging.error(f"Error fetching data: {e}")

Step 8: Define the Function to Run the Dune Query

Combine the previous functions into a single process that executes a query, waits for its completion, and then retrieves the results.

def run_dune_query(query_id):
    try:
        execution = execute_query(query_id)
        execution_id = execution.json()["execution_id"]
        executed_query_id = wait_for_execution(execution_id)
        query_id = executed_query_id.json()["query_id"]
        results = get_results(query_id)
        return dict(results.json())
    except Exception as e:
        logging.error(f"an error occurred: {e}")
        return None

Step 9: Define Functions to Fetch Specific Index Data

Create functions that fetch data for specific indexes (Alpha, Beta, Gamma, etc.) by calling the run_dune_query function with the appropriate query ID.

def get_alpha_index():
    return run_dune_query(query_ids["Alpha"])

def get_beta_index():
    return run_dune_query(query_ids["Beta"])

def get_gamma_index():
    return run_dune_query(query_ids["Gamma"])

def get_daily_narrative_index():
    return run_dune_query(query_ids["24h"])

def get_weekly_narrative_index():
    return run_dune_query(query_ids["7d"])

def get_monthly_narrative_index():
    return run_dune_query(query_ids["30d"])

def get_quarterly_narrative_index():
    return run_dune_query(query_ids["90d"])

Step 10: Define Query IDs

Define a dictionary that maps each index to its corresponding query ID on Dune Analytics.

query_ids = {
    "Alpha": "3804774",
    "Beta": "3804861",
    "Gamma": "3804881",
    "24h": "3594639",
    "7d": "3595951",
    "30d": "3600193",
    "90d": "3600267",
}

Step 11: Define Instruction String

Create a string containing instructions for the HiveAgent, explaining what the agent is responsible for and providing additional context about the indexes.

instruction = """ You are responsible for giving information about indexes and crypto narratives to get updated market data.
You can give information about ALPHA Index, Beta Index,Gama Index,Daily Crypto Narratives,Weekly Crypto Narratives,Mothly Crypto Narratives,Quarterly Crypto Narratives.

Additional information about these indexes.
Daily alpha index of the TOP 10 coins from all narratives based on Optimized Relative Strength
ALPHA Index is from 7D timeframe
BETA Index is from 30D timeframe
GAMMA Index is from 90D timeframe

... (additional details) ...
"""

Step 12: Create and Run the HiveAgent

Finally, create an instance of HiveAgent, passing in the functions, instructions, and configuration path. Then, run the agent.

my_agent = HiveAgent(
    name="crypto_narrative_document_agent",
    functions=[
        get_alpha_index,
        get_beta_index,
        get_gamma_index,
        get_daily_narrative_index,
        get_weekly_narrative_index,
        get_monthly_narrative_index,
        get_quarterly_narrative_index,
    ],
    instruction=instruction,
    config_path=get_config_path("hive_config.toml")
)

my_agent.run()

Running the Agent

With the environment set up and a basic understanding of the code structure, you are now ready to run the agent and see it in action.

Ensure your virtual environment is activated. You can test your agent by calling its Chat API endpoint to see the result.

Here’s an example using curl:

Step 1: Run the API server:

(venv) python hive_crypto_agent.py

Step 2: Open the Swagger Docs

http://localhost:8000/docs

Step 3: Choose the POST /api/vi/chat and test it:

curl --location 'localhost:8000/api/v1/chat' \
--header 'Content-Type: application/json' \
--data '{
    "user_id": "user123",
    "session_id": "session123",
    "chat_data": {
        "messages": [
            { "role": "user", "content": "Can I get weekly crypto report?" }
        ]
    }
}'

This will send a request to the API and provide you with a response, allowing you to verify the agent’s functionality.

Output

You can also chat with the Dune Agent using SwarmZero’s UI. You can set it up using the instructions in this repository.

As the next steps, you can proceed with testing if required.

Wrap Up

Congratulations! You've successfully set up, configured, and customized your Dune Agent using SwarmZero.ai.

PreviousAI AgentsNextBuild a News Agent with SwarmZero.ai using the GDELT API

Last updated