Tool Base Class API Reference

The Tool class is an abstract base class that all custom tools within Agent Forge must extend. It provides a standard structure for defining a tool's name, description, parameters, and execution logic.

ToolParameter Interface (from ../types)

Before detailing the Tool class, it's important to understand the ToolParameter interface, which defines the structure of each parameter a tool accepts. (A more detailed entry for ToolParameter will be in the Types reference section).

export interface ToolParameter {
  name: string; // The name of the parameter (used as a key in the params object).
  type: "string" | "number" | "boolean" | "array" | "object"; // The expected data type.
  description: string; // A natural language description of what the parameter is for.
  required: boolean; // Whether the parameter must be provided.
  default?: any; // An optional default value if the parameter is not provided and not required.
  // enum?: string[]; // Optional: If type is string, an array of allowed enum values.
}

Tool Abstract Class

Overview

When you create a custom tool, you will create a class that extends Tool. You'll need to provide a constructor that calls super() with the tool's metadata and implement the protected abstract run() method.

Constructor (to be called via super())

constructor(
  name: string,
  description: string,
  parameters: ToolParameter[] = [],
  returnType?: string
)

When implementing your custom tool, you'll call super() from your tool's constructor.

• name: string: A unique name for your tool. This name is used by the LLM to identify and call the tool.
• description: string: A clear, natural language description of what your tool does, what it's useful for, and what kind of input it expects. This is crucial for the LLM to understand when and how to use the tool.
• parameters: ToolParameter[] (optional): An array of ToolParameter objects defining the inputs your tool accepts. Defaults to an empty array if your tool takes no parameters.
• returnType?: string (optional): A natural language description of what the tool's run method returns (e.g., "a string containing the summary", "a JSON object with user details").

Readonly Properties

These properties are set by the constructor arguments.

• name: string: The name of the tool.
• description: string: The description of the tool.
• parameters: ToolParameter[]: An array of parameter definitions for the tool.
• returnType?: string: Description of the tool's output.

Public Methods

async execute(params: Record<string, any>): Promise<any>

This method is called by the Agent Forge system (or an agent) to run the tool. It first validates the provided params against the tool's parameters definition (checking for required parameters and correct types), applies any default values, and then calls your run() method.

• params: Record<string, any>: An object where keys are parameter names and values are the arguments for those parameters.
• Returns: A Promise that resolves to the output of your tool's run() method.
• Throws: An error if parameter validation fails or if your run() method throws an error.

getConfig(): ToolConfig

Returns a configuration object representing the tool's definition.

• Returns: A ToolConfig object (from ../types) containing name, description, parameters, and returnType.

getChatCompletionConfig(): ChatCompletionTool

Returns a configuration object formatted specifically for use with LLM chat completion APIs that support function/tool calling (e.g., OpenAI API).

• Returns: A ChatCompletionTool object (from token.js) structured for LLM consumption.

Abstract Method (to be implemented by subclasses)

protected abstract async run(params: Record<string, any>): Promise<any>

This is the core logic of your tool. You must implement this method in your custom tool class.

• params: Record<string, any>: An object containing the validated parameters for your tool, with defaults applied if any were defined and the parameters weren't provided.
• Returns: A Promise that resolves to the result of your tool's execution. This can be any value (e.g., a string, number, object).

Example: Creating a Custom Tool

import { Tool, ToolParameter } from "agent-forge"; // Assuming ToolParameter is re-exported or path adjusted

class MyCalculatorTool extends Tool {
  constructor() {
    const parameters: ToolParameter[] = [
      {
        name: "num1",
        type: "number",
        description: "The first number.",
        required: true,
      },
      {
        name: "num2",
        type: "number",
        description: "The second number.",
        required: true,
      },
      {
        name: "operation",
        type: "string",
        description: "The operation to perform (add, subtract, multiply, divide).",
        required: true,
        // enum: ["add", "subtract", "multiply", "divide"] // If ToolParameter supports enums
      },
    ];
    super(
      "MyCalculator",
      "Performs basic arithmetic operations (add, subtract, multiply, divide) on two numbers.",
      parameters,
      "A number representing the result of the calculation, or an error message string."
    );
  }

  protected async run(params: { num1: number; num2: number; operation: string }): Promise<number | string> {
    const { num1, num2, operation } = params;

    switch (operation.toLowerCase()) {
      case "add":
        return num1 + num2;
      case "subtract":
        return num1 - num2;
      case "multiply":
        return num1 * num2;
      case "divide":
        if (num2 === 0) {
          return "Error: Cannot divide by zero.";
        }
        return num1 / num2;
      default:
        return `Error: Unknown operation '${operation}'. Valid operations are add, subtract, multiply, divide.`;
    }
  }
}

// How it might be used (conceptual):
// const calculator = new MyCalculatorTool();
// calculator.execute({ num1: 10, num2: 5, operation: "add" })
//   .then(result => console.log("Calc Result:", result)) // Output: Calc Result: 15
//   .catch(error => console.error(error));

This Tool base class provides the necessary structure and validation for integrating custom functionalities into your Agent Forge agents.