From 52dfd3ecc31db17ae9c79aa826ffaa7b0a719792 Mon Sep 17 00:00:00 2001 From: Graham White Date: Wed, 28 Aug 2024 12:01:59 +0100 Subject: [PATCH 01/21] 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]); + } + } +} From 095f29d8fac5e9e784c89c7a20d1b81242ab27be Mon Sep 17 00:00:00 2001 From: Graham White Date: Thu, 29 Aug 2024 11:20:55 +0100 Subject: [PATCH 02/21] fix: linting errors --- docs/tools.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/tools.md b/docs/tools.md index 4299fcbb..8ed2358c 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -51,21 +51,25 @@ Tools MUST do the following: 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(); - } - ``` + + +```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 - } - ``` + + +```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 From 9a1a64544668c75548623f65c10d5a469daba872 Mon Sep 17 00:00:00 2001 From: Graham White Date: Thu, 29 Aug 2024 11:23:18 +0100 Subject: [PATCH 03/21] fix: example code indentation --- docs/tools.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/tools.md b/docs/tools.md index 8ed2358c..9952f05d 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -53,23 +53,23 @@ Tools MUST do the following: -```typescript -static { - this.register(); -} -``` + ```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 -} -``` + ```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 From 713685979b1f97d40796cefa57ec41690a94e50e Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 11:41:54 +0100 Subject: [PATCH 04/21] docs: make references to Tool and DynamicTool more accurate --- docs/tools.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tools.md b/docs/tools.md index 9952f05d..c7a2e30b 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -10,7 +10,7 @@ These tools extend the agent's abilities, allowing it to interact with external ### 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. +To create a tool, the `Tool` class must be extended/ implemented or `DynamicTool` created 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: @@ -51,7 +51,7 @@ Tools MUST do the following: 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 { @@ -61,7 +61,7 @@ Tools MUST do the following: - Implement the `_run()` method: - + ```typescript protected async _run(input: ToolInput, options?: BaseToolRunOptions) { From 484d9b12de9c7f7619b3f555b3d58c7f45d2197d Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 11:45:23 +0100 Subject: [PATCH 05/21] docs: best practice to set tool name property to the name of the class --- docs/tools.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tools.md b/docs/tools.md index c7a2e30b..85cf392b 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -24,6 +24,8 @@ Tools MUST do the following: - Be given a unique name: + Note: Convention and best practice is to set the tool's name to the name of its class + ```typescript name = "MyNewTool"; ``` From 644c240946985517d959dda6db5c1ce8a165b5d1 Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 11:57:39 +0100 Subject: [PATCH 06/21] docs: make the inputSchema description more complete --- docs/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools.md b/docs/tools.md index 85cf392b..6b614c96 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -40,7 +40,7 @@ Tools MUST do the following: - 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). + 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 can be specified using [Zod](https://github.com/colinhacks/zod) (recommended) or JSONSchema and must be a function (either sync or async). Zod effects (e.g. `z.object().transform(...)`) are not supported. The `inputSchema` definition must always be an object and pass validation by the `validateSchema()` function defined in [schema.ts](../src/internals/helpers/schema.ts). ```typescript // any Zod definition is good here, this is typical simple example From 5232b5c23fc79cdbb069f79adfd8061104a4e063 Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 12:00:30 +0100 Subject: [PATCH 07/21] docs: add serializable note --- docs/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools.md b/docs/tools.md index 6b614c96..bcf7e59d 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -51,7 +51,7 @@ Tools MUST do the following: - 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. + The unnamed static block is executed when your tool is called for the first time. It is used for registering your tool as `serializable` to the agent and any other custom initialisation that may be required. From ba71fe284d78a18d1456915e67acc87f2a64da84 Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 13:02:25 +0100 Subject: [PATCH 08/21] docs: clarify class parameters --- docs/tools.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/tools.md b/docs/tools.md index bcf7e59d..e3f579ff 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -16,6 +16,12 @@ Tools MUST do the following: - Implement the `Tool` class: + `MyNewToolOutput` is required, must be an implementation of `ToolOutput` such as `StringToolOutput` or `JSONToolOutput` + + `ToolOptions` is optional (default BaseToolOptions), constructor parameters that are passed during tool creation + + `ToolRunOptions` is optional (default BaseToolRunOptions), optional parameters that are passed to the run method + ```typescript export class MyNewTool extends Tool { // tool implementation From 608614834731cbbf235d0d1ba72cb160c90f0534 Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 13:05:06 +0100 Subject: [PATCH 09/21] docs: use full path name instead of aliases when referencing imports --- docs/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools.md b/docs/tools.md index e3f579ff..5fcc95cf 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -84,7 +84,7 @@ Tools MUST do the following: 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"; +import { ArXivTool } from "bee-agent-framework/tools/arxiv"; const llm = new OllamaChatLLM({ modelId: "insert-model-id-here", From a98b64fbee8250f0303b4cc47cbc7a42d7363798 Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 13:13:24 +0100 Subject: [PATCH 10/21] fix: inputSchema specification, name and extraneous options --- examples/tools/helloworld.ts | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/examples/tools/helloworld.ts b/examples/tools/helloworld.ts index 03596090..82cb7163 100644 --- a/examples/tools/helloworld.ts +++ b/examples/tools/helloworld.ts @@ -5,16 +5,20 @@ type ToolOptions = BaseToolOptions; type ToolRunOptions = BaseToolRunOptions; export class HelloWorldTool extends Tool { - name = "Helloworld"; + name = "HelloWorld"; description = "Says hello when asked for a special greeting."; - inputSchema = z.string(); + inputSchema = z.object({ + identifier: z + .string() + .describe("The identifier (person, object, animal, etc.) used to when saying Hello"), + }); static { this.register(); } - protected async _run(input: string, options?: BaseToolRunOptions): Promise { + protected async _run(input: string): Promise { return new StringToolOutput(`Hello, ${input}`); } } From e82c3876c316c11e4b0b2c79b87db1bc5fdbb505 Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 13:15:40 +0100 Subject: [PATCH 11/21] fix: camel case file names --- examples/tools/{helloworld.ts => helloWorld.ts} | 0 examples/tools/{openlibrary.ts => openLibrary.ts} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename examples/tools/{helloworld.ts => helloWorld.ts} (100%) rename examples/tools/{openlibrary.ts => openLibrary.ts} (100%) diff --git a/examples/tools/helloworld.ts b/examples/tools/helloWorld.ts similarity index 100% rename from examples/tools/helloworld.ts rename to examples/tools/helloWorld.ts diff --git a/examples/tools/openlibrary.ts b/examples/tools/openLibrary.ts similarity index 100% rename from examples/tools/openlibrary.ts rename to examples/tools/openLibrary.ts From 171e59bf757e3de759bd890a613034c366e1632b Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 13:22:27 +0100 Subject: [PATCH 12/21] fix: typo --- examples/tools/openLibrary.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tools/openLibrary.ts b/examples/tools/openLibrary.ts index cfa3fa6e..c45b173c 100644 --- a/examples/tools/openLibrary.ts +++ b/examples/tools/openLibrary.ts @@ -111,7 +111,7 @@ export class OpenLibraryTool extends Tool, options?: BaseToolRunOptions) { + protected async _run(input: ToolInput, options?: ToolRunOptions) { const params = createURLParams(input); const url = `https://openlibrary.org/search.json?${decodeURIComponent(params.toString())}`; const response = await fetch(url, { From 01e0dba80de041e4d7a91b97b239664343f564b2 Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 14:05:53 +0100 Subject: [PATCH 13/21] fix: inputSchema as a function --- docs/tools.md | 12 +++++++----- examples/tools/helloWorld.ts | 24 ++++++++++++++++-------- examples/tools/openLibrary.ts | 22 +++++++++++++--------- 3 files changed, 36 insertions(+), 22 deletions(-) diff --git a/docs/tools.md b/docs/tools.md index 5fcc95cf..fc99313b 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -46,13 +46,15 @@ Tools MUST do the following: - 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 can be specified using [Zod](https://github.com/colinhacks/zod) (recommended) or JSONSchema and must be a function (either sync or async). Zod effects (e.g. `z.object().transform(...)`) are not supported. The `inputSchema` definition must always be an object and pass validation by the `validateSchema()` function defined in [schema.ts](../src/internals/helpers/schema.ts). + 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 can be specified using [Zod](https://github.com/colinhacks/zod) (recommended) or JSONSchema. It must be a function (either sync or async). Zod effects (e.g. `z.object().transform(...)`) are not supported. The return value of `inputSchema` must always be an object and pass validation by the `validateSchema()` function defined in [schema.ts](../src/internals/helpers/schema.ts). ```typescript - // any Zod definition is good here, this is typical simple example - inputSchema = z.object({ - // list of key-value pairs - }); + inputSchema() { + // any Zod definition is good here, this is typical simple example + return z.object({ + // list of key-value pairs + }); + } ``` - Implement initialisation: diff --git a/examples/tools/helloWorld.ts b/examples/tools/helloWorld.ts index 82cb7163..a8a3b204 100644 --- a/examples/tools/helloWorld.ts +++ b/examples/tools/helloWorld.ts @@ -1,4 +1,10 @@ -import { BaseToolOptions, BaseToolRunOptions, StringToolOutput, Tool } from "@/tools/base.js"; +import { + BaseToolOptions, + BaseToolRunOptions, + StringToolOutput, + Tool, + ToolInput, +} from "@/tools/base.js"; import { z } from "zod"; type ToolOptions = BaseToolOptions; @@ -8,17 +14,19 @@ export class HelloWorldTool extends Tool { - return new StringToolOutput(`Hello, ${input}`); + protected async _run(input: ToolInput): Promise { + return new StringToolOutput(`Hello, ${input.identifier}`); } } diff --git a/examples/tools/openLibrary.ts b/examples/tools/openLibrary.ts index c45b173c..cd52bab8 100644 --- a/examples/tools/openLibrary.ts +++ b/examples/tools/openLibrary.ts @@ -97,15 +97,19 @@ export class OpenLibraryTool extends Tool Date: Fri, 30 Aug 2024 14:17:07 +0100 Subject: [PATCH 14/21] fix: linting error --- docs/tools.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tools.md b/docs/tools.md index fc99313b..1f8b8092 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -48,6 +48,8 @@ Tools MUST do the following: 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 can be specified using [Zod](https://github.com/colinhacks/zod) (recommended) or JSONSchema. It must be a function (either sync or async). Zod effects (e.g. `z.object().transform(...)`) are not supported. The return value of `inputSchema` must always be an object and pass validation by the `validateSchema()` function defined in [schema.ts](../src/internals/helpers/schema.ts). + + ```typescript inputSchema() { // any Zod definition is good here, this is typical simple example From 62cd5671fb8da8945f062a0d80716896965a7f6a Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 14:57:33 +0100 Subject: [PATCH 15/21] docs: camel case and correction of file names --- docs/tools.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tools.md b/docs/tools.md index 1f8b8092..ae053d1f 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -105,11 +105,11 @@ const agent = new BeeAgent({ ### 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. +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: +The [openlibrary](../examples/tools/openLibrary.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 From c796ca5e791c63fda909c7ab7b48b2ede2888759 Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 15:01:20 +0100 Subject: [PATCH 16/21] docs: add link to tools documentation --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9228dcbb..0afb1639 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ -

Open-source framework for building, deploying, and serving powerful agentic workflows at scale.

+

Open-source framework for building, deploying, and serving powerful agentic workflows at scale.

The Bee framework makes it easy to build agentic worfklows with leading open-source and proprietary models. We’re working on bringing model-agnostic support to any LLM to help developers avoid model provider lock-in. @@ -15,7 +15,7 @@ The Bee framework makes it easy to build agentic worfklows with leading open-sou ## Key Features - 🤖 **AI agents**: Use our powerful [Bee agent](https://github.com/i-am-bee/bee-agent-framework/tree/main?tab=readme-ov-file#get-started-with-bee) or [build your own](https://github.com/i-am-bee/bee-agent-framework/blob/main/docs/overview.md#agents). -- 🛠️ **Tools**: Use our [built-in tools](https://github.com/i-am-bee/bee-agent-framework/blob/main/docs/overview.md#tools) or create your own in Javascript/Python. +- 🛠️ **Tools**: Use our [built-in tools](https://github.com/i-am-bee/bee-agent-framework/blob/main/docs/overview.md#tools) or [create your own](https://github.com/i-am-bee/bee-agent-framework/blob/main/docs/tools.md) in Javascript/Python. - 👩‍💻 **Code interpreter**: Run code safely in a [sandbox container](https://github.com/i-am-bee/bee-code-interpreter). - 💾 **Memory**: Multiple [strategies](https://github.com/i-am-bee/bee-agent-framework/blob/main/docs/overview.md#memory) to optimize token spend. - ⏸️ **Serialization** Handle complex agentic workflows and easily pause/resume them [without losing state](https://github.com/i-am-bee/bee-agent-framework/blob/main/docs/overview.md#serializer). From 6ed783caf6ebf02ca5a97615c5a9a0cf860ce8e5 Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 15:08:08 +0100 Subject: [PATCH 17/21] docs: add import path to code example --- docs/tools.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/tools.md b/docs/tools.md index ae053d1f..6c7eb8eb 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -23,6 +23,9 @@ Tools MUST do the following: `ToolRunOptions` is optional (default BaseToolRunOptions), optional parameters that are passed to the run method ```typescript + import { BaseToolOptions, BaseToolRunOptions } from "bee-agent-framework/tools/base.js"; + type ToolOptions = BaseToolOptions; + type ToolRunOptions = BaseToolRunOptions; export class MyNewTool extends Tool { // tool implementation } From 8e590552112c55a73a159def4ad30dc68c87529f Mon Sep 17 00:00:00 2001 From: Graham White Date: Fri, 30 Aug 2024 15:12:17 +0100 Subject: [PATCH 18/21] fix: replace statusText with response.text() --- examples/tools/openLibrary.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tools/openLibrary.ts b/examples/tools/openLibrary.ts index cd52bab8..4b28fc37 100644 --- a/examples/tools/openLibrary.ts +++ b/examples/tools/openLibrary.ts @@ -123,7 +123,7 @@ export class OpenLibraryTool extends Tool Date: Mon, 2 Sep 2024 10:35:05 +0100 Subject: [PATCH 19/21] docs: remove js extension and add newlines --- docs/tools.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/tools.md b/docs/tools.md index 6c7eb8eb..8e29fbe0 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -23,9 +23,11 @@ Tools MUST do the following: `ToolRunOptions` is optional (default BaseToolRunOptions), optional parameters that are passed to the run method ```typescript - import { BaseToolOptions, BaseToolRunOptions } from "bee-agent-framework/tools/base.js"; + import { BaseToolOptions, BaseToolRunOptions } from "bee-agent-framework/tools/base"; + type ToolOptions = BaseToolOptions; type ToolRunOptions = BaseToolRunOptions; + export class MyNewTool extends Tool { // tool implementation } From 503d905810bb05fac2cfa6a30661fa6e177a63ae Mon Sep 17 00:00:00 2001 From: Graham White Date: Mon, 2 Sep 2024 15:31:12 +0100 Subject: [PATCH 20/21] chore: trigger build --- docs/tools.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/tools.md b/docs/tools.md index 8e29fbe0..414f8291 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -2,9 +2,7 @@ ## 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. +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 From e8e13c50725eb19c5425722b080cc366f9c5aeea Mon Sep 17 00:00:00 2001 From: Graham White Date: Mon, 2 Sep 2024 15:40:07 +0100 Subject: [PATCH 21/21] chore: trigger build --- docs/tools.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/tools.md b/docs/tools.md index 414f8291..8e29fbe0 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -2,7 +2,9 @@ ## 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. +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