# 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

```typescript
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

```typescript
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.

   ```typescript
   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.

   ```typescript
   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.

   ```typescript
   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:

```typescript
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.