Defining and Using Tools

Tools in AgentScope AI are modular, reusable functions that extend the capabilities of agents. They allow agents to interact with external APIs, perform computations, and handle specific tasks efficiently. Each tool consists of a defined schema, execution logic, and integration with external resources.

Creating a Tool

To define a tool, follow these steps:

1. Define the tool schema using zod for input validation.

2. Implement the tool’s execution logic.

3. Register the tool with AgentScope AI.

Example: Creating a Weather Information Tool

The following example demonstrates how to create a tool that fetches weather data for a given city.

src/tools/weatherInfo.ts

import { createTool } from "@agentscope/core";
import { z } from "zod";

const getWeatherInfo = async (city: string) => {
  // Replace with an actual API call to a weather service
  const data = await fetch(`https://api.weatherapi.com/v1/current.json?key=API_KEY&q=${city}`)
    .then((response) => response.json());
  return data;
};

export const weatherInfo = createTool({
  id: "GetWeatherInformation",
  inputSchema: z.object({
    city: z.string(),
  }),
  description: "Fetches the current weather information for a given city.",
  execute: async ({ context: { city } }) => {
    console.log("Fetching weather information for", city);
    return await getWeatherInfo(city);
  },
});

Adding a Tool to an Agent

Once a tool is created, it must be assigned to an agent for usage.

Example: Adding weatherInfo to an Agent

src/agents/weatherAgent.ts

import { Agent } from "@agentscope/core";
import * as tools from "../tools/weatherInfo";

export const weatherAgent = new Agent<typeof tools>({
  name: "WeatherAgent",
  instructions:
    "You are an assistant that provides current weather information. When asked about the weather, use the weather information tool.",
  model: {
    provider: "OPEN_AI",
    name: "gpt-4",
    toolChoice: "required",
  },
  tools: {
    weatherInfo: tools.weatherInfo,
  },
});

Registering the Agent with AgentScope AI

To activate the agent with its tools, it must be registered within the system.

src/index.ts

import { AgentScope } from "@agentscope/core";
import { weatherAgent } from "./agents/weatherAgent";

export const agentScope = new AgentScope({
  agents: { weatherAgent },
});

This ensures that the agent is available within the AgentScope AI environment.

Calling an Agent with a Tool

Agents use tools dynamically based on requests. Here’s how to interact with the weatherAgent.

src/index.ts

import { agentScope } from "./index";

async function main() {
  const agent = agentScope.getAgent("WeatherAgent");
  const response = await agent.generate("What’s the weather like in New York City today?");

  console.log(response.text);
}

main();

Debugging and Testing Tools

Tools can be tested independently using unit tests to ensure they function as expected.

Example: Unit Test for weatherInfo Tool

test("weatherInfo tool fetches data correctly", async () => {
  const result = await weatherInfo.execute({ context: { city: "New York" } });
  expect(result).toHaveProperty("temperature");
});