Tools

Tools in AINU are modular components that extend the functionality of an agent. They allow agents to perform specific tasks, such as fetching data, processing inputs, or interacting with external systems. Tools are highly flexible and can be dynamically created, configured, and passed to agents.

---

Tool Constructor

The Tool class is used to define and configure tools. Each tool has a name and a configuration object (ToolConfig) that specifies its behavior.

Constructor Signature

constructor(name: string, config: ToolConfig)

Parameters:

• name: A unique name for the tool.
• config: A ToolConfig object that defines the tool's description, parameters, handler, and optional context.

---

ToolConfig

The ToolConfig type defines the configuration options for a tool. This includes its description, input parameters, and the handler function that executes the tool's logic.

Available Parameters

Parameter	Type	Description
description	string	Required. A brief description of the tool's purpose.
parameters	`z.ZodTypeAny	Schema`
handler	(...args: any) => any	Optional. The function executed when the tool is invoked.
context	Record<string, any>	Optional. Additional context passed to the handler during execution.

Example

import { Tool } from "@ainulabs/ainu";
import { z } from "zod";

const weatherTool = new Tool("getWeather", {
  description: "Fetches the weather for a given location.",
  parameters: z.object({
    location: z.string(),
  }),
  handler: ({ location }) => `The weather in ${location} is sunny.`,
});

---

Using Tools with Agents

Tools can be passed to agents in several ways:

1. Through the Agent Constructor: Tools can be passed as part of the tools parameter when creating an agent.

   const agent = new Agent({
     provider,
     tools: [weatherTool],
   });

2. Using Agent Methods: Tools can be added, removed, or retrieved dynamically using the following methods:

   • putTool(tool: Tool): Adds a tool to the agent.
   • deleteTool(name: string): Removes a tool by its name.
   • findTool(name: string): Finds and retrieves a tool by its name.

   agent.putTool(weatherTool); // Add a tool
   agent.deleteTool("getWeather"); // Remove a tool
   const tool = agent.findTool("getWeather"); // Retrieve a tool

3. Passing Tools to generateText: Tools can be passed directly to the generateText method for one-time use.

   const response = await agent.generateText({
     prompt: "What's the weather in New York?",
     tools: [weatherTool],
   });

---

Advanced Tool Features

Error Handling and Context

The buildTool utility wraps the tool's handler function to provide error handling, result formatting, and optional context passing. This ensures that tools are robust and can handle unexpected errors gracefully.

---

Example: Creating and Using a Tool

Here’s a complete example of creating a tool and using it with an agent:

import { Agent, Anthropic, Tool } from "@ainulabs/ainu";
import { z } from "zod";

// Define a provider
const provider = new Anthropic({
  apiKey: "your-api-key",
});

// Define a tool
const weatherTool = new Tool("getWeather", {
  description: "Fetches the weather for a given location.",
  parameters: z.object({
    location: z.string(),
  }),
  handler: ({ location }) => `The weather in ${location} is sunny.`,
});

// Create an agent with the tool
const agent = new Agent({
  provider,
  tools: [weatherTool],
});

// Use the agent
(async () => {
  const response = await agent.generateText({
    prompt: "What's the weather in Paris?",
  });

  console.log(response.data?.text); // Output: "The weather in Paris is sunny."
})();

---

Summary

Tools are a powerful way to extend the functionality of agents in AINU. By defining tools with the Tool class and ToolConfig type, you can create modular, reusable components that handle specific tasks. Tools can be passed to agents during construction, added dynamically, or used directly in tasks, making them a flexible and essential part of the framework.