Writing your first tool in Node.js (with Typescript)

node-hash-tool contains a reference TypeScript Node.js 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/node-hash-tool

Tool Repo Structure

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

node-hash-tool
├── package-lock.json
├── package.json
├── tsconfig.json
├── tool.gpt
└── src
    ├── hash.ts
    └── tools.ts

Note: The tsconfig.json file is only required for tools written in TypeScript. It is not necessary for tools written in JavaScript.

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 infer a tool's usage. 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 npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- hash

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 Node.js toolchain (node and npm)
2. Sets up a working directory for the tool
3. Installs the dependencies from the tool's package.json and package-lock.json
4. Projects the call arguments onto environment variables (DATA and ALGO)
5. Runs npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- hash

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 npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- hash

Tool Metadata

The tool.gpt file also provides the following metadata for use in Obot:

• !metadata:*:category which tags tools 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

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

---
!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 npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- hash

---
!metadata:*:category
Crypto

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

Implementing Business Logic

As we saw earlier, the npm command invoked by the Tool Body passes hash as an argument to the tool script.

npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- hash

To figure out what this resolves to, let's inspect the tool script defined in package.json:

  "scripts": {
    "tool": "node --no-warnings --loader ts-node/esm src/tools.ts"
  },

This means that when the Tool Body is executed, the effective command that runs is:

node --no-warnings --loader ts-node/esm src/tools.ts hash

Note: The --loader ts-node/esm option, in conjunction with the contents of tsconfig.json, is the "special sauce" that lets us run TypeScript code directly without transpiling it to JavaScript first.

To summarize, when the Hash tool is called by an agent, src/tools.ts gets run with hash as an argument.

Let's walk through the src/tools.ts to understand what happens at runtime:

// ...
const cmd = process.argv[2]
try {
    switch (cmd) {
        case 'hash':
            console.log(hash(process.env.DATA, process.env.ALGO))
            break
        default:
            console.log(`Unknown command: ${cmd}`)
            process.exit(1)
    }

} catch (error) {
    // Print the error to stdout so that it can be captured by the GPTScript
    console.log(`${error}`)
    process.exit(1)
}

This code implements a simple CLI that wraps business logic in a try/catch block and forwards any exceptions to stdout. Writing errors to stdout instead of stderr is crucial because only stdout is returned to the agent, while stderr is discarded.

Note: The simple CLI pattern showcased above is also easily extensible; adding business logic for new tools becomes a matter of adding a new case to the switch statement.

For example, if we wanted to add a new tool to verify a given hash, we'd add a verify case:

switch (cmd) {
    case 'verify':
        console.log(verify(process.env.HASH, process.env.DATA, process.env.ALGO))
        break
    case 'hash':
        // ...
    default:
        // ...
    }

And the body of the Verify tool would pass verify to the tool script instead of hash:

Name: Verify
# ...

#!/usr/bin/env npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- verify

When "hash" is passed as an argument, the code extracts the data and algo tool arguments from the respective environment variables, then passes them to the hash function.

The hash function is where the bulk of the business logic is implemented.

import { createHash } from 'node:hash';

const SUPPORTED_ALGORITHMS = ['sha256', 'md5'];

export function hash(data: string = '', algo = 'sha256'): string {
  if (data === '') {
    throw new Error("A non-empty data argument must be provided");
  }

  if (!SUPPORTED_ALGORITHMS.includes(algo)) {
    throw new Error(`Unsupported hash algorithm ${algo} not in [${SUPPORTED_ALGORITHMS.join(', ')}]`);
  }

  return JSON.stringify({
    algo,
    hash: createHash(algo).update(data).digest('hex'),
  });
}

It starts off by validating the data and algo arguments. When an argument is invalid, the function throws 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.

Once it determines that all the arguments are valid, it calculates the hash and writes a JSON object to stdout. This object contains the hash and the algorithm used to generate it.

  // ...
  return JSON.stringify({
    algo,
    hash: createHash(algo).update(data).digest('hex'),
  });

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 package.json, src/tools.ts, and src/hash.ts

{
  "type": "module",
  "scripts": {
    "tool": "node --no-warnings --loader ts-node/esm src/tools.ts"
  },
  "dependencies": {
    "@types/node": "^20.16.11",
    "ts-node": "^10.9.2",
    "typescript": "^5.4.5"
  },
  "devDependencies": {}
}

// src/tools.ts
import { hash } from './hash.ts'

if (process.argv.length !== 3) {
    console.error('Usage: node tool.ts <command>')
    process.exit(1)
}

const cmd = process.argv[2]
try {
    switch (cmd) {
        case 'hash':
            console.log(hash(process.env.DATA, process.env.ALGO))
            break
        default:
            console.log(`Unknown command: ${cmd}`)
            process.exit(1)
    }

} catch (error) {
    // Print the error to stdout so that it can be captured by the GPTScript
    console.log(`${error}`)
    process.exit(1)
}

// src/hash.ts
import { createHash } from 'node:hash';

const SUPPORTED_ALGORITHMS = ['sha256', 'md5'];

export function hash(data: string = '', algo = 'sha256'): string {
  if (data === '') {
    throw new Error("A non-empty data argument must be provided");
  }

  if (!SUPPORTED_ALGORITHMS.includes(algo)) {
    throw new Error(`Unsupported hash algorithm ${algo} not in [${SUPPORTED_ALGORITHMS.join(', ')}]`);
  }

  return JSON.stringify({
    algo,
    hash: createHash(algo).update(data).digest('hex'),
  });
}

Testing src/tools.ts and src/hash.ts Locally

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

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

1. Install dependencies

   npm install

2. Run the tool with some test arguments:

   Command	Output
   DATA='foo' npm run tool hash	{ "algo": "sha256", "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" }
   npm run tool hash	Error: A data argument must be provided
   DATA='foo' ALGO='md5' npm run tool hash	{ "algo": "md5", "hash": "acbd18db4cc2f85cedef654fccc4a4d8" }
   DATA='foo' ALGO='whirlpool' npm run tool hash	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