Skip to content

Index

Overview

This guide contains guidelines for contributing to the development of Mechs and offer services.

In order to offer services, anyone can create and deploy their own Mech agents. First, developers can use existing pieces of code, called tools, or create and publish new ones. Once tools are created, Mech agents can be deployed on the Olas Registry. At this point, a Mech contract can be created via the Mech MarketPlace. Mech agents, when creating on-chain Mech contracts via the Mech Marketplace can choose among three distinct payment models, each defining how the requester can pay for the service requested Specifically, the payment models are the following:

  • Native: A fixed-price model where the requester pays using the chain with native token native token for each delivered service;

  • Token: Similar to the Native model, but payments are made using a specified ERC20 token;

  • Nevermined subscription: A dynamic pricing model that allows flexible pricing across different services.

Mech agent deployment and related Mech contract creation process is handled by the Mech quickstart, and the main inputs to provide are the list of tools to be used, and the chosen payment model.

The detailed instructions to create tools, test them locally and deploy a Mech agent, and accrue payments can be found below.

1. Creating and publishing a tool

In order to contribute to Mechs' abilities, you can create and publish a tool. In order to do so, follow the instructions below.

1. 1. Creating a tool

Requirements: - Python >= 3.10 - Poetry >=1.4.0

In order to create a tool, the steps are as follows:

1. Fork the mech repository and clone the forked copy. You may use GitHub's UI or its CLI tools:

gh repo fork https://github.com/valory-xyz/mech --clone=true

2. Install the dependencies, set up a remote registry, and fetch the third-party packages from IPFS. You may use the following command after replacing the value for the AUTHORNAME variable:

AUTHORNAME=author

cd mech && \
poetry install && \
poetry run autonomy init --remote --ipfs --author $AUTHORNAME && \
poetry run autonomy packages sync --update-packages

3. Create the tool's structure by using the following command, after replacing the values for the AUTHORNAME and TOOL_NAME variables:

AUTHORNAME=author
TOOL_NAME=tool_name

TOOL_PATH=packages/"$AUTHORNAME"/customs/"$TOOL_NAME"
YEAR=$(date +"%Y")

mkdir -p $TOOL_PATH && \
cat > $TOOL_PATH/component.yaml <<EOF
name: $TOOL_NAME
author: $AUTHORNAME
version: 0.1.0
type: custom
description: Tool description
license: Apache-2.0
aea_version: '>=1.0.0, <2.0.0'
fingerprint:
    __init__.py:
    $TOOL_NAME.py:
fingerprint_ignore_patterns: []
entry_point: $TOOL_NAME.py
callable: run
dependencies: {}
EOF

for file in __init__.py "$TOOL_NAME.py"; do
  cat > $TOOL_PATH/$file <<EOF
# -*- coding: utf-8 -*-
# ------------------------------------------------------------------------------
#
#   Copyright $YEAR Valory AG
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       https://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.
#
# ------------------------------------------------------------------------------

EOF
done

cat >> "$TOOL_PATH/$TOOL_NAME.py" <<EOF
"""The implementation of the $TOOL_NAME tool."""


def run(*args, **kwargs):
    """The callable for the $TOOL_NAME tool."""
    # TODO: Implement the tool logic
    print(f"Running $TOOL_NAME with {args=} and {kwargs=}.)

EOF

poetry run autonomy packages lock

This command will generate the following structure, with template code:

packages/  
 ├── authorname/  
 │   ├── customs/  
 │   │   ├── tool_name/  
 │   │   │   ├── component.yaml
 │   │   │   ├── tool_name.py
 │   │   │   ├── __init__.py

4. Now that your tool's structure is set up, all that's left is to configure the tool component and implement the tool's functionality in Python. The component.yaml file contains the tool's configuration. Here is an explanation of its fields: - name: the name of the tool. - author: the author's name. - version: the version of the tool. - type: the component type of the open-autonomy framework. This should be custom. - description: the description of the tool. - license: the licencing of the tool. It should be Apache-2.0. - aea_version: the supported open-aea version. - fingerprint: unique hash of the tool. This is auto-generated by the framework's autonomy packages lock command. - fingerprint_ignore_patterns: ignore patterns for the fingerprint's generation. - entry_point: the module which contains the tool's implementation. - callable: points to the function which is called in the tool's module. - dependencies: the module's dependencies. You may specify them in the following format:

dependencies:
    dependency_1:
        version: ==0.5.3
    dependency_2:
        version: '>=2.20.0'

1. 2. Publishing the tool

Before proceeding, make sure that you are inside the poetry environment: 

poetry shell

1. Create the package hash, by running the following commands, from the root:

autonomy packages lock

At this point you will be prompted to choose "dev" or "third-part". Choose "dev".

2. Push the packages to IPFS: 

autonomy push-all

3. Mint the tool here as a component on the Olas Registry; For this is needed: an address (EOA), and the hash of the meta-data file. In order to generate this hash, click on “Generate Hash & File” and provide the following information: name (name of the tool); description (of the tool); version (this needs to match the version in the file component.yaml); package hash (this can be found in packages.json under the packages folder); NFT image URL (for instance on IPFS, supported domains are listed in the window). In order to push an image on IPFS, there are two options:

  1. Use this script. Place the image in a folder called mints in .jpg format. Then, run the script: 

    python ipfs_pin.py

  2. Use the mech-client, replacing <file_name> with the name of your file: 

    poetry add mech-client &&\
mechx push-to-ipfs ./<file_name>

After this, the tool can be deployed to be used by a Mech.

2. Testing a tool by deploying a Mech locally

In order to test a tool that you developed, it is possible to do this by deploying a Mech locally and send it requests, specifying your tool as the one to be used. In order to do so, follow the instructions below.

2. 1. Setup

Requirements: Python == 3.10; Poetry >= 1.4.0 ; Docker Engine ; Docker Compose ; Yarn == 1.22.19 ; Node == 20.18.1; npx/npm == 10.8.2 ;

1. Run the followings in the terminal: 

docker pull valory/open-autonomy-tendermint:0.18.3
docker pull valory/oar-mech:bafybeicg5ioivs2ryaim6uf3cws2ashc5ldxtrvxgbjbhv3y2ic63qx324

2. Clone the mech-quickstart repository:

git clone https://github.com/valory-xyz/mech-quickstart.git

3. Rename the file .api_keys.json.example into .api_keys.json (don't change the dummy keys), and the file .tools_to_packages_hash.json.example into .tools_to_packages_hash. You can modify this example by adding your tool (name and hash).

4. Create a tenderly virtual testnet, following these steps:

  • Create an account/connect to Tenderly: https://dashboard.tenderly.co/.

  • Click on “Project” and then “Create project”, as on the following picture.

    create_project

    Give a name to the project and click again on “Create project”.

  • Then click on "Virtual Test Nets" on the left menu (or on the following icon if the menu bar is collapsed): testnet

  • Then click on “Create Virtual TestNet”.

  • Choose “Gnosis chain” as the parent network, give a name to the virtual testnet and un-mark “Use latest block” in the State Sync section in order to enter the following custom block: 36619660.

  • Finally, click on the “Create” button.

  • After you are redirected to the TestNet "Explorer" page, copy the RPC Admin HTTPS link, it will be used later.

5. Setup the virtual testnet, by following these steps:

  • In a separate folder, clone the ai-registry-mech repository: 
    git clone https://github.com/KahanMajmudar/ai-registry-mech.git
  • Run the following: 
    git submodule update --init --recursive

  • Then change the branch to "testnet-setup".

  • Crate an access token on Tenderly, by clicking on the profile icon (top-right), then on "Account settings", "Access tokens" in the left menu, then "Generate access token". Choose a label (it is only informative) and then click on "Generate". Copy the generated token.

  • Connect to tenderly in the terminal: 

    tenderly login --access-key <access_token>
    where <access_token> has to be replaced with the access key created as before.

  • In the file hardhat.config.js, change the url of virtual_testnet (line 47) to the RPC of the testnet created on tenderly. On lines 141 and 142, change "project" and "username" strings with the ones found on tenderly in the opened project. This can be found by clicking on "Project" on the tenderly dashboard, then selecting the opened project, and "Settings" on the right menu. The "project" corresponds to "Project slug" and "username" corresponds to "Account slug".

  • In the file globals.json, change "networkURL" on line 6 to the RPC of the testnet and "privateKey" (line 7) to the private key of your wallet.

  • Install the dependencies using the following: 

    yarn install

  • Fund the EOA address in tenderly (with the default amount). In order to do so, click on “Fund account” on the webpage of the virtual testnet created before, enter the address to fund, the quantity and the token. For a custom token, click on “Use custom token address” and enter the token address. Then click on “Fund”.

  • Run the script to deploy the contracts which are necessary to test the Mech locally: 

    bash setup-tdly.sh

  • From the file globals.json in the ai-registry-mech folder, copy the following values and paste them in the corresponding lines of the utils.py file of the mech-quickstart folder:

    a. "mechMarketplaceProxyAddress" -> line 490 ;

    b. "mechFactoryFixedPriceNativeAddress" -> line 495 ;

    c. "mechFactoryFixedPriceTokenAddress" -> line 500.

2. 2. Running the Mech

0. Change folder to the mech-quickstart one and then create environment (in terminal): 

poetry shell
poetry install

1. Run the mech service (in terminal):

bash run_service.sh

2. Provide information when prompted, in particular:

  • "Please enter a GNOSIS RPC URL" -> enter the RPC endpoint (https address copied earlier).

  • "Which type of mech do you want to deploy?" -> this corresponds to the payment model of the Mech (Native: native token ; Token: ERC20 tokens; Nevermined: subscription); default is Native.

Other values can be left to default (by pressing enter when prompted).

3. When prompted to do so, add funds to the required address.

4. Logs are visible with: 

docker logs mech_abci_0 --follow

The activity of the Mech is visible on the virtual testnet.

5. Stop the mech service: 

./stop_service.sh

2. 3. Sending a request

1. In another folder, clone the mech-client repository: 

git clone https://github.com/valory-xyz/mech-client.git

2. Install the mech-client package: 

pip install -e.

3. If the mech-client folder does not contain a file ethereum_private_key.txt already, create it and paste in it the private key of your EOA.

4. Add the following at the end of the dictionary in mech_client/configs/mechs.json: 

"tdly": {
    "agent_registry_contract": "0x9dEc6B62c197268242A768dc3b153AE7a2701396",
    "service_registry_contract": "0x9338b5153ae39bb89f50468e608ed9d764b755fd",
    "rpc_url": ,
    "wss_endpoint": "wss://gnosis-chiado-rpc.publicnode.com",
    "ledger_config": {
        "address": ,
        "chain_id": 10200,
        "poa_chain": false,
        "default_gas_price_strategy": "eip1559",
        "is_gas_estimation_enabled": false
    },
    "mech_marketplace_config": {
        "mech_marketplace_contract": "",
        "priority_mech_address": "",
        "response_timeout": 300,
        "payment_data": "0x"
    },
    "gas_limit": 500000,
    "price": 10000000000000000,
    "contract_abi_url":"https://gnosis.blockscout.com/api/v2/smart-contracts/{contract_address}",
    "transaction_url":"https:/gnosisscan.iotx/{transaction_digest}",
    "subgraph_url": ""
}

Replace rpc_url and address with the RPC endpoint address, and mech_marketplace_contract with the mech marketplace address found in tenderly. Change also priority_mech_address with the address of your Mech (it can be found in mech-quickstart/.mech_quickstart/local_config.json, key mech_address). This address can be found in the tab "Contracts" of the page of the Testnet created above:

alt text

The contract is the last one created in the list of contracts found in tenderly.

5. Comment lines 560 to 566 in mech_client/marketplace_interact.py.

6. Run the following command in terminal in the mech-client repository: 

mechx interact <prompt> --tool <tool_name> --chain-config tdly

where <prompt> is replaced by the chosen prompt and <tool_name> by the name of your tool.

7. You can see the data of the request in the testnet page on tenderly, in the tab "Explorer".

4. Deploying a Mech on the Mech Marketplace

In order to register a Mech on the Mech Marketplace - including Mech service creation and deployment, and Mech contract deployment- follow the instructions below.

4. 1. Setup

Requirements: Python == 3.10; Poetry >= 1.4.0 ; Docker Engine ; Docker Compose

1. Run the followings in the terminal: 

docker pull valory/open-autonomy-tendermint:0.18.3
docker pull valory/oar-mech:bafybeicg5ioivs2ryaim6uf3cws2ashc5ldxtrvxgbjbhv3y2ic63qx324

2. Create an EOA (add xDAI amounts on this account whenever requested).

3. Create a RPC endpoint, for instance using https://www.nodies.app/. The steps are the following ones:

  • Create an account;

  • Create a project;

  • Add an app to this project (choose the Gnosis chain);

  • Copy the HTTPS link (under “Endpoint networks”) → this will be requested later;

5. Create a Google API Key and an OpenAI API key.

6. Clone the mech-quickstart repository:

git clone https://github.com/valory-xyz/mech-quickstart.git

7. Rename the file .api_keys.json.example into .api_keys.json and add OpenAI and Google API keys in the file. Also rename the file .tools_to_packages_hash.json.example into .tools_to_packages_hash. You can modify this example by adding your tool (name and hash).

8. Change folder to mech-quickstart and create environment (in terminal): 

cd mech-quickstart
poetry shell
poetry install

4. 2. Running the mech service

1. Run the mech service (in terminal):

bash run_service.sh

2. Provide information when prompted (in particular for the RPC endpoint, provide the https address copied earlier).

3. In order to send a request to it, follow the steps in the section 2.3 above, replacing the RPC endpoint with the one created here.

4. Logs are visible with: 

docker logs mech_abci_0 --follow

5. You can send a request, by changing the value of priority_mech_address in the dictionary of the chain chosen when setting up the RPC endpoint in .mech_client/configs/mechs.json by the address of your Mech. This address can be found in .mech_quickstart/local_config.json, key mech_address. Then use the mechx command: 

mechx interact <prompt> --tool <tool_name> --chain-config <chain>

where <prompt> is replaced by the chosen prompt and <tool_name> by the name of your tool, and <chain> is replaced by the name of the chosen chain.

6. In order to add new tools when the mech is deployed, add its name and hash in .tools_to_packages_hash.json.

7. Stop the mech service: 

./stop_service.sh

5. Registering an agent on the Mech Marketplace

In case you have already a Mech service deployed on Olas Registry and want to put it to work for other agents, you only need to register it on the Mech Marketplace.

In order to do so, follow the instructions below.

1. Find here the address of MechMarketPlaceProxy for the chosen network.

2. Trigger the function create of this contract with the following inputs (in order):

  • The service id.

  • The Mech Factory address for the selected network and payment model. To find the correct address, refer to the configuration file. Search for the address that matches the chosen payment model:

    • For Native, look for the MechFactoryFixedPriceNative address.

    • For Token: MechFactoryFixedPriceToken

    • For Nevermined, find MechFactoryNvmSubscriptionNative.

  • The maximum price of the Mech (also called maxDeliveryRate), converted to Wei. For instance, for a price of 1 xDAI, this is equal to 10^18.

You can find a script for triggering this function here for each payment model. Clone the repository: 

git clone https://github.com/Sfgangloff/ai-registry-mech.git

Update the submodules, install the dependencies and compile the contracts: 

git submodule update --init --recursive
yarn install
npx hardhat compile

Choose the one which corresponds to the chosen payment model, and replace the name of the network on line 6. Then add your private key (privateKey), service id (serviceId) and maximum price (payload) in the globals file which corresponds to the chosen network. Finally, run the script. For instance, for a native fixed price Mech: 

cd scripts/mech_registration
node create_mech_native.js

/!\ The private key must correspond to the EOA used to deploy the service.

3. You will find the address of the Mech contract in the logs. It will also be written in the globals file.

6. How to accrue the payments

In order to accrue the payments of your Mech, find here the BalanceTracker contract which corresponds to the payment model of your Mech. The key is the following for each of the three payment models:

  • Native: BalanceTrackerFixedPriceNative

  • Token: BalanceTrackerFixedPriceToken

  • Nevermined: BalanceTrackerNvmSubscriptionNative

Enter its address in the scan of the chosen network. Click on "Contract" and then "Write Contract" and trigger the function processPaymentByMultisig. Enter the address of your Mech and click on "Write". This will transfer the funds stored in the Mech Marketplace to the address of your Mech contract.

Troubleshooting :

  1. Issue: 0xa25d624C49eE3691a2B25223e3a899c77738FDa3 not in list of participants: "[0xc062E6cfdCb48700de374905BF66A0BAD1Ef36E7]" Solution: Make sure the private keys inside keys.json match the address in ALL_PARTICIPANTS env

  2. Issue: Exception raised while executing task: No module named 'anthropic' Solution: Make sure the deps are listed in tool/component.yaml and aea-config.yaml and are pinned

  3. Issue: Tool changes not being reflected
    Solution: Update the tool hash if there are any changes inside the tools or configs. To update run autonomy packages lock and update the tool hash (if needed) inside TOOLS_TO_PACKAGE_HASH

  4. Issue: env formatting issues
    Solution: Make sure there are no whitespaces in dicts and lists and are represented as a string. So example this is the correct format. Also pay attention to utf coding of the " in str fields. 

    MECH_TO_CONFIG='{"0xbead38e4C4777341bB3FD44e8cd4D1ba1a7Ad9D7":{"use_dynamic_pricing":false,"is_marketplace_mech":true}}'
    ⚠️ It is possible sometimes for the env to contain \u201c or \u201d. This means it is using a quotation mark character that is not accepted, replace the quotation mark character " for a compatible one.

  5. Issue: ValueError: {'code': -32603, 'message': 'Filter with id: 1950087 does not exist.'}. Error when requesting transaction digest: {'code': -32010, 'message': 'AlreadyKnown'}
    Solution: Please check RPC is correct or change to a different provider

  6. Issue: Service \'\'api_key\'\' not found in KeyChain.
    Solution: Make sure to add proper key names inside API_KEYS env

  7. Issue: Error: Number of agents cannot be greater than available keys. Solution: It's possible the code editor is formatting env files so double check the format of the keys and values. So for example, for 1 agent system

    Wrong: 
ETHEREUM_LEDGER_RPC_0 = (
    "https://rpc.gnosischain.com/"
)

Right: ETHEREUM_LEDGER_RPC_0="https://rpc.gnosischain.com/"

  8. Issue: Client.init() got an unexpected keyword argument 'proxies'" Solution: Try to pin httpx to 0.25.2 inside tool's component.yaml and aea-config.yaml

  9. Issue: Tool is not supported.
    Solution: Make sure the tool_name is inside the ALLOWED_TOOLS inside the tool.py

  10. Issue: Incompatible counter_callback.
    Solution: If your tool is going to use the counter_callback function available at the run template and your tool is using a model that is not in this list, please contact the mech developers for your model to be included, otherwise do not use the counter_callback function

  11. Issue: Port already in use.
    Solution: When running locally the mech agent if you face an error of the type ERROR: failed to start node: failed to listen on 127.0.0.1:26658: listen tcp 127.0.0.1:26658: bind: address already in use
    Then check at the CLI which process is using the port: 

    $ lsof -i :26658
    and kill the process with: 
    $ kill -9 process_id

Appendix : What is the Mech Marketplace ?

The Mech Marketplace is a collection of smart contracts designed to facilitate seamless interactions between agents or applications (referred to as requesters) and Mech agents which provide task-based services. Essentially, it acts as a relay, enabling secure, on-chain payments while ensuring efficient task requests and service delivery.

Specifically, the Mech Marketplace enables the following.

  • Effortless Mech contract creation and delivery: Any agent registered on the Olas Service registry can quickly deploy a Mech contract with minimal inputs. This streamlined process allows agents to rapidly offer their service and receive on-chain payments.

  • Seamless task execution requests: Requesters—whether agents or applications—can opt to directly submit service requests through the Mech Marketplace. The on-chain contracts manage payments, ensuring a smooth and transparent interaction between requesters and Mech agents.

  • Guaranteed task completion: A take-over mechanism is in place: if a designated Mech fails to respond within a deadline specified by the requester, any other available Mech can step in to complete the task. Therefore, there is a high likelihood that every request is fulfilled, maintaining the system’s reliability. Karma - A reputation score system: The Karma contract tracks each Mech’s performance by maintaining a reputation score. This reflects how often a Mech successfully completes assigned tasks versus how often it fails. Mech agents that maintain high Karma scores are considered more trustworthy by requesters. Assuming honest participation, Mech agents that maintain high Karma scores are considered more trustworthy by requesters.

  • Competitive environment: Mechs are incentivized to deliver outstanding results promptly in order to maintain high Karma scores and secure more tasks.