Writing your first tool in Python

python-hash-tool contains a reference Python implementation of the Hash tool.

This guide walks through the structure and design of the tool and outlines the packaging requirements for Obot

To clone this repo and follow along, run the following command:

git clone [email protected]:obot-platform/python-hash-tool

Tool Repo Structure

The directory tree below highlights the files required to implement Hash in Python and package it for Obot.

python-hash-tool
├── hash.py
├── requirements.txt
└── tool.gpt

Defining the Hash Tool

The tool.gpt file contains GPTScript Tool Definitions which describe a set of tools that can be used by agents in Obot. Every tool repository must have a tool.gpt file in its root directory.

The tools defined in this file must have a Name and Description that will help agents understand what the tool does, what it returns (if anything), and all the Parameters it takes. Agents use these details to figure out when and how to use the tool. We call the section of a tool definition that contains this info a Preamble.

We want the Hash tool to return the hash of some given data. It would also be nice to support a few different algorithms for the agent to choose from.

Let's take a look at the Preamble for Hash to see how that's achieved:

Name: Hash
Description: Generate a hash of data using the given algorithm and return the result as a hexadecimal string
Param: data: The data to hash
Param: algo: The algorithm to generate a hash with. Supports "sha256" and "md5". Default is "sha256"

Breaking this down a bit:

• The Preamble above declares a tool named Hash
• The Param fields enumerate the arguments that an agent must provide when calling Hash, data and algo
• In this case, the description of the algo parameter outlines the valid options (sha256 or md5) and defines a default value (sha256)
• The Description explains what Hash returns with respect to the given arguments; the hash of data using the algorithm selected with algo

Immediately below the Preamble is the Tool Body, which tells Obot how to execute the tool:

 #!/usr/bin/env python3 ${GPTSCRIPT_TOOL_DIR}/hash.py

This is where the magic happens.

To simplify, when an agent calls the Hash tool, Obot reads this line and then:

1. Downloads the appropriate Python toolchain
2. Sets up a working directory for the tool and creates a virtual environment
3. Installs the dependencies from the requirements.txt, if present
4. Projects the call arguments onto environment variables (DATA and ALGO)
5. Runs python3 ${GPTSCRIPT_TOOL_DIR}/hash.py

Putting it all together, here's the complete definition of the Hash tool.

Name: Hash
Description: Generate a hash of data using the given algorithm and return the result as a hexadecimal string
Param: data: The data to hash
Param: algo: The algorithm to generate a hash with. Default is "sha256". Supports "sha256" and "md5".

#!/usr/bin/env python3 ${GPTSCRIPT_TOOL_DIR}/hash.py

Tool Metadata

The snippet below (from the tool.gpt file) also provides the following metadata for use in Obot:

• !metadata:*:category which tags all tools in the tool.gpt file with the Crypto category to promote organization and discovery
• !metadata:*:icon which assigns https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg as the tool icon to all tools in the tool.gpt file

Note: * is a wildcard pattern that applies the metadata to all tools in a tool.gpt.

---
!metadata:*:category
Crypto

---
!metadata:*:icon
https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg

Note: Metadata can be applied to a specific tool by either specifying the exact name (e.g. !metadata:Hash:category) or by adding the metadata directly to a tool's Preamble

Name: Hash
Metadata: category: Crypto
Metadata: icon: https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg

Complete tool.gpt

---
Name: Hash
Description: Generate a hash of data using the given algorithm and return the result as a hexadecimal string
Param: data: The data to hash
Param: algo: The algorithm to generate a hash with. Supports "sha256" and "md5". Default is "sha256"

#!/usr/bin/env python3 ${GPTSCRIPT_TOOL_DIR}/hash.py

---
!metadata:*:category
Crypto

---
!metadata:*:icon
https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg

Implementing Business Logic

The hash.py file executed by the Tool Body is the concrete implementation of the tool's business logic.

Let's walk through the code to understand how it works.

if __name__ == '__main__':
    try:
        main()
    except Exception as err:
        # Print err to stdout to return the error to the agent
        print(f'Error: {err}')
        sys.exit(1)

Starting at the bottom, the main function is called in a try block so that any runtime exceptions caught are written to stdout. This is important because everything written to stdout is returned to the agent when the tool call is completed, while everything written to stderr is discarded. Using this pattern ensures that when a tool call fails, the calling agent is informed of the failure.

Moving on, the main function implements the core logic of the Hash tool.

SUPPORTED_HASH_ALGORITHMS = ['sha256', 'md5']

def main():
    # Extract the tool's `data` argument from the env
    data = os.getenv('DATA')
    if not data:
        raise ValueError('A data argument must be provided')

    # Extract the tool's `algo` argument from the env and default to `sha256`
    algo = os.getenv('ALGO', 'sha256')
    if algo not in SUPPORTED_HASH_ALGORITHMS:
        # Return the supported algorithms in the error message to help agents choose a valid
        # algorithm the next time they call this tool
        raise ValueError(f'Unsupported hash algorithm: {algo} not in {SUPPORTED_HASH_ALGORITHMS}')
    #...

It starts off by extracting the tool's arguments from the respective environment variables and validates them. When an argument is invalid, the function raises an exception that describes the validation issue in detail. The goal is to provide useful information that an agent can use to construct valid arguments for future calls. For example, when an invalid algo argument is provided, the code returns an error that contains the complete list of valid algorithms.

After validating the tool arguments, it calculates the hash and writes a JSON object to stdout. This object contains the hash and the algorithm used to generate it.

    # ...
    # Generate the hash
    hash_obj = hashlib.new(algo)
    hash_obj.update(data.encode('utf-8'))

    # Return the hash along with the algorithm used to generate it.
    # Providing more information in the tool's response makes it easier for agents to keep
    # track of the context.
    print(json.dumps({
        'algo': algo,
        'hash': hash_obj.hexdigest()
    }))

Note: Producing structured data with extra contextual info (e.g. the algorithm) is considered good form. It's a pattern that improves the Agent's ability to correctly use the tool's result over time.

Complete hash.py

import hashlib
import json
import os
import sys

SUPPORTED_HASH_ALGORITHMS = ['sha256', 'md5']


def main():
    # Extract the tool's `data` argument from the env
    data = os.getenv('DATA')
    if not data:
        raise ValueError('A data argument must be provided')

    # Extract the tool's `algo` argument from the env and default to `sha256`
    algo = os.getenv('ALGO', 'sha256')
    if algo not in SUPPORTED_HASH_ALGORITHMS:
        # Return the supported algorithms in the error message to help assistants choose a valid
        # algorithm the next time they call this tool
        raise ValueError(f'Unsupported hash algorithm: {algo} not in {SUPPORTED_HASH_ALGORITHMS}')

    # Generate the hash
    hash_obj = hashlib.new(algo)
    hash_obj.update(data.encode('utf-8'))

    # Return the hash along with the algorithm used to generate it.
    # Providing more information in the tool's response makes it easier for assistants to keep
    # track of the context.
    print(json.dumps({
        'algo': algo,
        'hash': hash_obj.hexdigest()
    }))


if __name__ == '__main__':
    try:
        main()
    except Exception as err:
        # Print err to stdout to return the error to the assistant
        print(f'Error: {err}')
        sys.exit(1)

Testing hash.py Locally

Before adding a tool to Obot, verify that the Python business logic works on your machine.

To do this, run through the following steps in the root of your local fork:

1. Set up a virtual environment:

   python3 -m venv venv
   source venv/bin/activate

2. Activate the virtual environment:

   source venv/bin/activate

3. Install and freeze dependencies:

   pip install -r requirements.txt
   pip freeze > requirements.txt

4. Run the tool with some test arguments:

   Command	Output
   DATA='foo' python3 hash.py	{ "algo": "sha256", "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" }
   python3 hash.py	Error: A data argument must be provided
   DATA='foo' ALGO='md5' python3 hash.py	{ "algo": "md5", "hash": "acbd18db4cc2f85cedef654fccc4a4d8" }
   DATA='foo' ALGO='whirlpool' python3 hash.py	Error: Unsupported hash algorithm: whirlpool not in ['sha256', 'md5']

Adding The Hash tool to Obot

Before a tool can be used by an agent, an admin must first add the tool to Obot by performing the steps below:

1. Navigate to the Obot admin UI in a browser and open the Tools page by clicking the Tools button in the left drawer

   
2. Click the Register New Tool button on the right

   
3. Type the tool repo reference into the modal's input box and click Register Tool

   

Once the tool has been added, you can search for it by category or name on the Tools page to verify

Using The Hash tool in an agent

To use the Hash tool in an agent, open the agent's Edit page, then:

1. Click the Add Tool button under either the Agent Tools or User Tools sections

   
2. Search for "Hash" or "Crypto" in the tool search pop-out and select the Hash Tool

   
3. Ask the agent to generate a hash