Hive Agent Kit

GitHub - hivenetwork-ai/hive-agent-py: This library provides you with an easy way to create and run Hive Agents.GitHub

This library provides you with an easy way to create and run Hive Agents.

Project Requirements

Install Python (>= 3.11):

Download from the official Python website.
Follow the installation instructions for your OS.

Acquiring an OpenAI API Key:

Sign up or log in to your OpenAI account at OpenAI API.
Navigate to the API section and generate a new API key.

Refer to the OpenAI Rate Limits for detailed information.

Supported Large Language Models (LLMs)

Here are the supported large language models in Hive Agent:

gpt-4o
gpt-4o-mini
gpt-4-turbo
gpt-4
gpt-3.5-turbo
gpt-3.5-turbo-instruct

Installation

You can either directly install from pip:

pip install git+https://github.com/hivenetwork-ai/hive-agent-py.git@main

Or add it to your requirements.txt file:

hive-agent @ git+https://github.com/hivenetwork-ai/hive-agent-py@main

Optional Dependencies

To install with the optional web3 dependencies, you can specify them as follows:

pip install git+https://github.com/hivenetwork-ai/hive-agent-py.git@main#egg=hive-agent[web3]

Or add it to your requirements.txt file:

hive-agent[web3] @ git+https://github.com/hivenetwork-ai/hive-agent-py@main

Environment Setup

You need to specify an OPENAI_API_KEY in a .env file in this directory.
Make a copy of the .env.example file and rename it to .env.

Configuration Setup

To use a configuration file with your HiveAgent, follow these steps:

Create a Configuration File:
Create a TOML file (e.g., hive_config.toml) in your project directory. (See hive_config_example.toml).
Specify the Configuration Path:
When creating a HiveAgent instance, provide the relative or absolute path to your configuration file.

from hive_agent import HiveAgent

import os

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

simple_agent = HiveAgent(
    name="Simple Agent",
    functions=[],
    instruction="your instructions for this agent's goal",
    config_path=get_config_path("hive_config.toml") # ./hive_config.toml works too 
)

Usage

First, import the HiveAgent class:

from hive_agent import HiveAgent

Load your environment variables:

from dotenv import load_dotenvload_dotenv()

Then create a HiveAgent instance:

my_agent = HiveAgent(
    name="my_agent",
    functions=[],
    instruction="your instructions for this agent's goal",
)

Then, run your agent:

my_agent.run()

Finally, call the API endpoint, /api/v1/chat, to see the result:

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": "Who is Satoshi Nakamoto?" }
        ]
    }
}'

Advanced Usage

You configure your Hive Agent by adding tools, you can create a swarm of agents to handle a complex task, and you can add a retriever to get semantic information. Below are some examples of how you can do it:

Adding tools

You can create tools that help your agent handle more complex tasks. Here's an example:

import os
from typing import Optional, Dict
from web3 import Web3
from hive_agent import HiveAgent
from dotenv import load_dotenv

load_dotenv()

rpc_url = os.getenv("RPC_URL") # add an ETH Mainnet HTTP RPC URL to your `.env` file

def get_transaction_receipt(transaction_hash: str) -> Optional[Dict]:
    """
    Fetches the receipt of a specified transaction on the Ethereum blockchain and returns it as a dictionary.

    :param transaction_hash: The hash of the transaction to fetch the receipt for.
    :return: A dictionary containing the transaction receipt details, or None if the transaction cannot be found.
    """
    web3 = Web3(Web3.HTTPProvider(rpc_url))

    if not web3.is_connected():
        print("unable to connect to Ethereum")
        return None

    try:
        transaction_receipt = web3.eth.get_transaction_receipt(transaction_hash)
        return dict(transaction_receipt)
    except Exception as e:
        print(f"an error occurred: {e}")
        return None

if __name__ == "__main__":
    my_agent = HiveAgent(
        name="my_agent",
        functions=[get_transaction_receipt]
    )
    
    my_agent.run()

    """
    [1] send a request:
    
    ```
    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": "Which address initiated this transaction - 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060?" }
            ]
        }
    }'
    ```
    
    [2] result:
    
    The address that initiated the transaction with hash 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060 is 0xA1E4380A3B1f749673E270229993eE55F35663b4.
    """

Creating a Swarm

You can create a swarm of agents to collaborate on complex tasks. Here's an example of how to set up and use a swarm:

from hive_agent.swarm import HiveSwarm
from hive_agent.agent import HiveAgent
from hive_agent.sdk_context import SDKContext

from hive_agent.llms.utils import llm_from_config
from hive_agent.utils import tools_from_funcs
from hive_agent.llms.claude import ClaudeLLM
import asyncio

# Create SDK Context
sdk_context = SDKContext(config_path="./hive_config_example.toml")

def save_report():
    return "save_item_to_csv"

def search_on_web():
    return "search_on_web"

#You can use the default config using default_config or the config of a specific agent by using the get_config method.
llm = llm_from_config(sdk_context.get_config("target_agent_id"))
tools = tools_from_funcs([search_on_web])
claude = ClaudeLLM(llm=llm, tools=tools)
    
# Create individual agents
agent1 = HiveAgent(name="Research Agent", instruction="Conduct research on given topics", sdk_context=sdk_context, functions=[search_on_web], llm=claude)
agent2 = HiveAgent(name="Analysis Agent", instruction="Analyze data and provide insights", sdk_context=sdk_context, functions=[save_report])
agent3 = HiveAgent(name="Report Agent", instruction="Compile findings into a report", sdk_context=sdk_context, functions=[])

# Create swarm
swarm = HiveSwarm(name="Research Team", description="A swarm of agents that collaborate on research tasks",
                 instruction="Be helpful and collaborative", functions=[], agents=[agent1, agent2, agent3], sdk_context=sdk_context)


async def chat_with_swarm():
    return await swarm.chat("Can you analyze the following data: [1, 2, 3, 4, 5]")

if __name__ == "__main__":
    asyncio.run(chat_with_swarm())

Adding Retriever

You can add retriever tools to create vector embeddings and retrieve semantic information. It will create vector index for every pdf documents under 'hive-agent-data/files/user' folder and can filter files with required_exts parameter.

Hive agent supports ".md", '.mdx' ,".txt", '.csv', '.docx', '.pdf' file types.
Hive agent supports 4 type of retriever (basic, chroma, pinecone-serverless, pinecone-pod) and controlled with retrieval_tool parameter.

import os
from typing import Optional, Dict
from web3 import Web3
from hive_agent import HiveAgent
from dotenv import load_dotenv

load_dotenv()

if __name__ == "__main__":
    my_agent = HiveAgent(
        name="retrieve-test",
        functions=[],
        retrieve = True,
        required_exts = ['.md'],
        retrieval_tool='chroma'
    )

    my_agent.run()

    """
    [1] send a request:

    ```
    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": "Which endpoints should I call to create vector index?" }
            ]
        }
    }'

Read the full tutorial here.

PreviousContributing to SwarmZero NextAgent API Schema

Last updated 21 hours ago