Skip to content

mech-tools-dev

Overview

This guide explains how to contribute to the Mech ecosystem by developing and offering services. Anyone can offer services by creating and deploying their own Mech agents. The process typically involves the following steps:

  1. Tool development: Developers can either reuse existing tools (modular components of Mechs) or create and publish new ones.

  2. Agent deployment: Once the necessary tools are ready, a Mech agent can be deployed and registered on the Olas Registry.

  3. Contract creation: A Mech contract can then be created via the Mech Marketplace. When doing so, developers must choose a payment model that determines how requesters will pay for services.

There are three available payment models:

  • Native: A fixed-price model where the requester pays in the chain’s 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 enables flexible pricing and access to multiple services through a single subscription.

Detailed instructions for creating tools, testing them locally, deploying Mech agents, and receiving payments are provided 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.

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

1. 1. Creating a tool

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

1. Fork and clone the mech-tools-dev repository.

  • Option 1: Fork the repository from the GitHub page. Then, clone your fork using:
git clone https://github.com/<your-username>/mech-tools-dev.git
  • Option 2: To clone and fork in a single command, you can use Github's CLI tools:
gh repo fork https://github.com/valory-xyz/mech-tools-dev --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-tools-dev && \
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 you need 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 (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);

  • [Optional] 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:

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

    python ipfs_pin.py

  • 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. Running a Mech locally

In order to deploy a Mech agent, register it on the Mech Marketplace and run it locally in order to test your tools, you can use the quickstart.

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.