From 9524032ef6ce671a3ef15dade97f15e95bd1854e Mon Sep 17 00:00:00 2001 From: Graham White Date: Wed, 28 Aug 2024 12:01:59 +0100 Subject: [PATCH] docs: initial commit of developer information about tools --- docs/overview.md | 2 +- docs/tools.md | 101 ++++++++++++++++++++++++++ examples/tools/helloworld.ts | 20 ++++++ examples/tools/openlibrary.ts | 132 ++++++++++++++++++++++++++++++++++ 4 files changed, 254 insertions(+), 1 deletion(-) create mode 100644 docs/tools.md create mode 100644 examples/tools/helloworld.ts create mode 100644 examples/tools/openlibrary.ts diff --git a/docs/overview.md b/docs/overview.md index 57683129..0ef78ec2 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -105,7 +105,7 @@ The framework provides out-of-the-box tools. | `OpenMeteoTool` | Retrieves current, previous, or upcoming weather for a given destination. | | ➕ [Request](https://github.com/i-am-bee/bee-agent-framework/discussions) | | -To create your own tool, you need to either implement the `BaseTool` class ([example](../examples/tools/customHttpRequest.ts)) or use `DynamicTool.` +To create your own tool, you need to either implement the `Tool` class or use `DynamicTool.` More information is available in the [tool documentation](tools.md). ### Cache diff --git a/docs/tools.md b/docs/tools.md new file mode 100644 index 00000000..4299fcbb --- /dev/null +++ b/docs/tools.md @@ -0,0 +1,101 @@ +# Tools + +## Introduction + +Tools in the context of an agent refer to additional functionalities or capabilities integrated with the agent to perform specific tasks beyond text processing. + +These tools extend the agent's abilities, allowing it to interact with external systems, access information, and execute actions. + +## Development + +### Writing a new tool + +To create a tool, the `Tool` or `DynamicTool` class must be implemented from [tools base](../src/tools/base.ts). When starting to write tools, it is recommended to implement the `Tool` class. The `DynamicTool` class is an extension of the `Tool` class that allows for dynamic forms of input. Refer to the list of [examples](#examples) for some simple examples or any of the built-in tools in order to guide the creation of new tools. + +Tools MUST do the following: + +- Implement the `Tool` class: + + ```typescript + export class MyNewTool extends Tool { + // tool implementation + } + ``` + +- Be given a unique name: + + ```typescript + name = "MyNewTool"; + ``` + +- Provide a natural language description of what the tool does: + + ❗Important: this description is used by the agent to determine when the tool should be used. It's probably the most important aspect of your tool and you should experiment with different natural language descriptions to ensure the tool is used in the correct circumstances. + + ```typescript + description = "Takes X action when given Y input resulting in Z output"; + ``` + +- Declare an input schema: + + This is used to define the format of the input to your tool. The agent will formalise the natural language input(s) it has received and structure them into the fields described in the tool's input. The input schema is specified using [Zod](https://github.com/colinhacks/zod). + + ```typescript + // any Zod definition is good here, this is typical simple example + inputSchema = z.object({ + // list of key-value pairs + }); + ``` + +- Implement initialisation: + + The unnamed static block is executed when your tool is called for the first time. It is used for registering your tool to the agent and any other custom initialisation that may be required. + + ```typescript + static { + this.register(); + } + ``` + +- Implement the `_run()` method: + + ```typescript + protected async _run(input: ToolInput, options?: BaseToolRunOptions) { + // insert custom code here + // MUST: return an instance of the output type specified in the tool class definition + // MAY: throw an instance of ToolError upon unrecoverable error conditions encountered by the tool + } + ``` + +### Using tools with agents + +In order for a tool to be of some utility within an agent, you must enable the agent with knowledge of the tool. To do this, the tool code module must be imported into the agent and passed to the tools array during creation of a `BeeAgent`. An example can be found in the [bee agent](../examples/agents/bee.ts) or you can use a code snippet such as the one below that creates an agent with the built-in [ArXiv tool](../src/tools/arxiv.ts): + +```typescript +import { ArXivTool } from "@/tools/arxiv.js"; + +const llm = new OllamaChatLLM({ + modelId: "insert-model-id-here", +}); + +const agent = new BeeAgent({ + llm, + memory: new TokenMemory({ llm }), + tools: [new ArXivTool()], +}); +``` + +## Examples + +### Hello World + +The simplest form of an example tool is the [helloworld](../examples/tools/helloworld.ts) tool. This example implements the Tool class and will simply prepend the word "Hello" to a given input such as "Please give a special greeting to Bee!". It is not intended for usage with any agents since the functionality provided is highly trivial. However, it may serve as a starter template for writing new tools. + +### Open Library + +The [openlibrary](../examples/tools/helloworld.ts) tool allows an agent to query the [Open Library](https://openlibrary.org/) via its [book search API](https://openlibrary.org/dev/docs/api/search). This functionality injects knowledge about book metadata (not book content) into an agent. It serves as an example for several key aspects of tool creation: + +- Implementing the `Tool` class +- Specifying the input schema to a tool +- Calling out to a third-party service and handling responses and errors +- Using `JSONToolOutput` to return JSON formatted data to the agent diff --git a/examples/tools/helloworld.ts b/examples/tools/helloworld.ts new file mode 100644 index 00000000..03596090 --- /dev/null +++ b/examples/tools/helloworld.ts @@ -0,0 +1,20 @@ +import { BaseToolOptions, BaseToolRunOptions, StringToolOutput, Tool } from "@/tools/base.js"; +import { z } from "zod"; + +type ToolOptions = BaseToolOptions; +type ToolRunOptions = BaseToolRunOptions; + +export class HelloWorldTool extends Tool { + name = "Helloworld"; + description = "Says hello when asked for a special greeting."; + + inputSchema = z.string(); + + static { + this.register(); + } + + protected async _run(input: string, options?: BaseToolRunOptions): Promise { + return new StringToolOutput(`Hello, ${input}`); + } +} diff --git a/examples/tools/openlibrary.ts b/examples/tools/openlibrary.ts new file mode 100644 index 00000000..cfa3fa6e --- /dev/null +++ b/examples/tools/openlibrary.ts @@ -0,0 +1,132 @@ +import { + BaseToolOptions, + BaseToolRunOptions, + Tool, + ToolInput, + JSONToolOutput, + ToolError, +} from "@/tools/base.js"; +import { z } from "zod"; +import { createURLParams } from "@/internals/fetcher.js"; + +type ToolOptions = BaseToolOptions; +type ToolRunOptions = BaseToolRunOptions; + +export interface OpenLibraryResponse { + numFound: number; + start: number; + numFoundExact: boolean; + num_found: number; + q: string; + offset: number; + docs: { + _version_: number; + key: string; + title: string; + subtitle: string; + alternative_title: string; + alternative_subtitle: string; + cover_i: number; + ebook_access: string; + ebook_count_i: number; + edition_count: number; + edition_key: string[]; + format: string[]; + publish_date: string[]; + lccn: string[]; + ia: string[]; + oclc: string[]; + public_scan_b: boolean; + isbn: string[]; + contributor: string[]; + publish_place: string[]; + publisher: string[]; + seed: string[]; + first_sentence: string[]; + author_key: string[]; + author_name: string[]; + author_alternative_name: string[]; + subject: string[]; + person: string[]; + place: string[]; + time: string[]; + has_fulltext: boolean; + title_suggest: string; + title_sort: string; + type: string; + publish_year: number[]; + language: string[]; + last_modified_i: number; + number_of_pages_median: number; + place_facet: string[]; + publisher_facet: string[]; + author_facet: string[]; + first_publish_year: number; + ratings_count_1: number; + ratings_count_2: number; + ratings_count_3: number; + ratings_count_4: number; + ratings_count_5: number; + ratings_average: number; + ratings_sortable: number; + ratings_count: number; + readinglog_count: number; + want_to_read_count: number; + currently_reading_count: number; + already_read_count: number; + subject_key: string[]; + person_key: string[]; + place_key: string[]; + subject_facet: string[]; + time_key: string[]; + lcc: string[]; + ddc: string[]; + lcc_sort: string; + ddc_sort: string; + }[]; +} + +export class OpenLibraryToolOutput extends JSONToolOutput { + isEmpty(): boolean { + return !this.result || this.result.numFound === 0 || this.result.docs.length === 0; + } +} + +export class OpenLibraryTool extends Tool { + name = "OpenLibrary"; + description = + "Provides access to a library of books with information about book titles, authors, contributors, publication dates, publisher and isbn."; + + inputSchema = z.object({ + title: z.string().optional(), + author: z.string().optional(), + isbn: z.string().optional(), + subject: z.string().optional(), + place: z.string().optional(), + person: z.string().optional(), + publisher: z.string().optional(), + }); + + static { + this.register(); + } + + protected async _run(input: ToolInput, options?: BaseToolRunOptions) { + const params = createURLParams(input); + const url = `https://openlibrary.org/search.json?${decodeURIComponent(params.toString())}`; + const response = await fetch(url, { + signal: options?.signal, + }); + if (!response.ok) { + throw new ToolError("Request to Open Library API has failed!", [ + new Error(response.statusText), + ]); + } + try { + const json = await response.json(); + return new OpenLibraryToolOutput(json); + } catch (e) { + throw new ToolError("Request to Open Library has failed to parse!", [e]); + } + } +}