Compass Virtuals SDK

The Compass Virtuals SDK is a powerful framework that revolutionizes how agents interact with DeFi. This SDK allows all developers on Virtuals to create AI agents that can autonomously interact with DeFi, opening a completely new set of possibilities for Virtuals agents, without needing to grapple with Solidity, bytecode, or scattered documentation.

  • Check out the Compass Virtuals SDK on Pypi here
  • Read to full blogpost here

Getting Started

Follow the steps below to get your agents up and running with the Compass Virtuals SDK in less than 5 minutes

Step 1: Install the SDK

Terminal
pip install compass.virtuals_sdk

Step 2: Configure your environment

Create a .env file with:

.env
ETHEREUM_RPC_URL=<JSON RPC NODE URL>
ETHEREUM_PRIVATE_KEY=<PRIVATE KEY>
GAME_API_KEY=<api key>

You can get an rpc url from a provider like Anker, or check your Metamask settings to see which node it talks to.

Step 3: Run the sample agent

Want to try out the capabilities offered by this SDK? Then you can run our simple agent provided in our package.

Terminal
python -c 'import compass.virtuals_sdk.simple_agent as s; s.compass_agent.compile(); s.compass_agent.run()'

Your agent will:

  1. Fetch its wallet address
  2. Query on-chain pricing data
  3. Build and execute transactions (if funds are available)

Tip: You can easily prevent the agent from having access to funds by providing an invalid PRIVATE_KEY in the .env file.

Building your own agent

The SDK is packed with tools to help you build the agent of your dreams. Here’s an example of what simple agent code looks like:

agent.py
from game_sdk.game.agent import Agent, WorkerConfig

from compass.api_client import Chain
from compass.virtuals_sdk.api_wrapper import (
    AaveV3,
    Aerodrome,
    Others,
    UniswapV3,
)
from compass.virtuals_sdk.config import api_key
from compass.virtuals_sdk.shared_defaults import get_state_fn
from compass.virtuals_sdk.wallet import Wallet

available_chains = [i.value for i in Chain]
worker_instruction = "Interact with your assigned defi protocol."

compass_agent = Agent(
    api_key=api_key,
    name="A defi agent that can operate on multiple defi exchanges",
    agent_goal=f"Make some money. Your ethereum wallet address is can be obtained via the wallet worker.When you need to set the sender or user of a transaction request, set if to to your wallet address. When you must choose between chains, choose one of {available_chains}",
    agent_description="defi agent",
    get_agent_state_fn=get_state_fn,
    workers=[
        WorkerConfig(cls.id, cls.worker_description, cls.get_state_fn, cls.action_space)
        for cls in [Wallet, Aerodrome, AaveV3, Others, UniswapV3]
    ],
)

Note that each of the classes that we provide for suggested WorkerConfig’s contains an id, worker_description, get_state_fn, and action_space. You can change any of these as you like. The action_space is the only really crucial part.

If you would like to pick and choose which tools you use with which agents, then as well as all tools being listed in the respectiveaction_space, each tool is set as a method on the helper classes. For example, you can get the game_sdk Function instance for checking on-chain balances from compass.virtuals_sdk.api_wrapper.Others.generic_balance_get.