feat(tools): add OpenAPI tool (#246)

Ref: #105

Signed-off-by: Akihiko Kuroda <[email protected]>

docs/tools.md

@@ -25,6 +25,7 @@ These tools extend the agent's abilities, allowing it to interact with external
 | `WebCrawlerTool`                                                          | Retrieve content of an arbitrary website.                                                                     |
 | `OpenMeteoTool`                                                           | Retrieve current, previous, or upcoming weather for a given destination.                                      |
 | `MilvusDatabaseTool`                                                      | Perform retrieval queries (search, insert, delete, manage collections) against a MilvusDatabaseTool database. |
+| `OpenAPITool`                                                             | Send requests to and receive responses from API server.                                                       |
 | ➕ [Request](https://github.com/i-am-bee/bee-agent-framework/discussions) |                                                                                                               |
 
 All examples can be found [here](/examples/tools).

package.json

@@ -208,7 +208,8 @@
     "ollama": "^0.5.11",
     "openai": "^4.67.3",
     "openai-chat-tokens": "^0.2.8",
-    "sequelize": "^6.37.3"
+    "sequelize": "^6.37.3",
+    "yaml": "^2.6.1"
   },
   "peerDependenciesMeta": {
     "@aws-sdk/client-bedrock-runtime": {
@@ -258,6 +259,9 @@
     },
     "sequelize": {
       "optional": true
+    },
+    "yaml": {
+      "optional": true
     }
   },
   "devDependencies": {

src/tools/openapi.test.ts

@@ -0,0 +1,66 @@
+import { OpenAPITool } from "@/tools/openapi.js";
+import { verifyDeserialization } from "@tests/e2e/utils.js";
+const cat_spec =
+  '{\
+    "openapi": "3.0.0",\
+    "info": {\
+      "title": "Cat Facts API",\
+      "description": "A simple API for cat facts",\
+      "version": "1.0.0"\
+    },\
+    "servers": [\
+      {\
+        "url": "https://catfact.ninja",\
+        "description": "Production server"\
+      }\
+    ],\
+    "paths": {\
+      "/fact": {\
+        "get": {\
+          "summary": "Get a random cat fact",\
+          "description": "Returns a random cat fact.",\
+          "responses": {\
+            "200": {\
+              "description": "Successful response",\
+              "content": {\
+                "application/json": {\
+                  "schema": {\
+                    "$ref": "#/components/schemas/Fact"\
+                  }\
+                }\
+              }\
+            }\
+          }\
+        }\
+      }\
+    },\
+    "components": {\
+      "schemas": {\
+        "Fact": {\
+          "type": "object",\
+          "properties": {\
+            "fact": {\
+              "type": "string",\
+              "description": "The cat fact"\
+            }\
+          }\
+        }\
+      }\
+    }\
+  }';
+
+describe("Base Tool", () => {
+  beforeEach(() => {
+    vi.clearAllTimers();
+  });
+
+  describe("OpenAPITool", () => {
+    it("Serializes", () => {
+      const tool = new OpenAPITool({ name: "OpenAPITool", openApiSchema: cat_spec });
+
+      const serialized = tool.serialize();
+      const deserialized = OpenAPITool.fromSerialized(serialized);
+      verifyDeserialization(tool, deserialized);
+    });
+  });
+});

src/tools/openapi.ts

@@ -0,0 +1,175 @@
+/**
+ * Copyright 2024 IBM Corp.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { join } from "path";
+
+import {
+  BaseToolOptions,
+  BaseToolRunOptions,
+  StringToolOutput,
+  Tool,
+  ToolError,
+  ToolEmitter,
+} from "@/tools/base.js";
+import { Callback, Emitter } from "@/emitter/emitter.js";
+import { GetRunContext } from "@/context.js";
+import { ValueError } from "@/errors.js";
+import { SchemaObject } from "ajv";
+import { parse } from "yaml";
+import { isEmpty } from "remeda";
+
+export interface OpenAPIToolOptions extends BaseToolOptions {
+  name: string;
+  description?: string;
+  openApiSchema: any;
+  apiKey?: string;
+  httpProxyUrl?: string;
+}
+
+export interface OpenAPIEvents {
+  beforeFetch: Callback<{ url: URL }>;
+  afterFetch: Callback<{ data: OpenAPIToolOutput }>;
+}
+
+export class OpenAPIToolOutput extends StringToolOutput {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly result = "",
+  ) {
+    super();
+    this.status = status;
+    this.statusText = statusText;
+    this.result = result ?? "";
+  }
+}
+
+export class OpenAPITool extends Tool<OpenAPIToolOutput, OpenAPIToolOptions> {
+  name = "OpenAPI";
+  description = `OpenAPI tool that performs REST API requests to the servers and retrieves the response. The server API interfaces are defined in OpenAPI schema. 
+Only use the OpenAPI tool if you need to communicate to external servers.`;
+  openApiSchema: any;
+  protected apiKey?: string;
+  protected httpProxyUrl?: string;
+
+  inputSchema(): SchemaObject {
+    return {
+      type: "object",
+      required: ["path", "method"],
+      oneOf: Object.entries(this.openApiSchema.paths).flatMap(([path, pathSpec]: [string, any]) =>
+        Object.entries(pathSpec).map(([method, methodSpec]: [string, any]) => ({
+          additionalProperties: false,
+          properties: {
+            path: {
+              const: path,
+              description:
+                "Do not replace variables in path, instead of, put them to the parameters object.",
+            },
+            method: { const: method, description: methodSpec.summary || methodSpec.description },
+            ...(methodSpec.requestBody?.content?.["application/json"]?.schema
+              ? {
+                  body: methodSpec.requestBody?.content?.["application/json"]?.schema,
+                }
+              : {}),
+            ...(methodSpec.parameters
+              ? {
+                  parameters: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: methodSpec.parameters
+                      .filter((p: any) => p.required === true)
+                      .map((p: any) => p.name),
+                    properties: methodSpec.parameters.reduce(
+                      (acc: any, p: any) => ({
+                        ...acc,
+                        [p.name]: { ...p.schema, description: p.name },
+                      }),
+                      {},
+                    ),
+                  },
+                }
+              : {}),
+          },
+        })),
+      ),
+    } as const satisfies SchemaObject;
+  }
+
+  public readonly emitter: ToolEmitter<Record<string, any>, OpenAPIToolOutput, OpenAPIEvents> =
+    Emitter.root.child({
+      namespace: ["tool", "web", "openAPITool"],
+      creator: this,
+    });
+
+  static {
+    this.register();
+  }
+
+  public constructor(options: OpenAPIToolOptions) {
+    super(options);
+    this.openApiSchema = parse(options.openApiSchema);
+    if (!this.openApiSchema?.paths) {
+      throw new ValueError("Server is not specified!");
+    }
+  }
+
+  protected async _run(
+    input: Record<string, any>,
+    _options: Partial<BaseToolRunOptions>,
+    run: GetRunContext<typeof this>,
+  ) {
+    let path: string = input.path || "";
+    const url = new URL(this.openApiSchema.servers[0].url);
+    Object.keys(input.parameters ?? {}).forEach((key) => {
+      const value = input.parameters[key];
+      const newPath = path.replace(`{${key}}`, value);
+      if (newPath == path) {
+        url.searchParams.append(key, value);
+      } else {
+        path = newPath;
+      }
+    });
+    url.pathname = join(url.pathname, path);
+    // eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
+    const headers: { [key: string]: string } = { Accept: "application/json" };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    await this.emitter.emit("beforeFetch", { url: url });
+    try {
+      const response = await fetch(url.toString(), {
+        body: !isEmpty(input.body) ? input.body : undefined,
+        method: input.method.toLowerCase(),
+        headers: headers,
+        signal: run.signal,
+      });
+      const text = await response.text();
+      const output = new OpenAPIToolOutput(response.status, response.statusText, text);
+      await this.emitter.emit("afterFetch", { data: output });
+      return output;
+    } catch (err) {
+      throw new ToolError(`Request to ${url} has failed.`, [err]);
+    }
+  }
+  createSnapshot() {
+    return {
+      ...super.createSnapshot(),
+      openApiSchema: this.openApiSchema,
+      apiKey: this.apiKey,
+      httpProxyUrl: this.httpProxyUrl,
+    };
+  }
+}

tests/e2e/tools/openapi.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Copyright 2024 IBM Corp.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { beforeEach, expect } from "vitest";
+import { OpenAPITool } from "@/tools/openapi.js";
+
+describe("OpenAPITool", () => {
+  let instance: OpenAPITool;
+
+  // Simple API spec for a cat fact API
+  // Assisted by WCA@IBM
+  // Latest GenAI contribution: ibm/granite-20b-code-instruct-v2
+
+  const cat_spec =
+    '{\
+    "openapi": "3.0.0",\
+    "info": {\
+      "title": "Cat Facts API",\
+      "description": "A simple API for cat facts",\
+      "version": "1.0.0"\
+    },\
+    "servers": [\
+      {\
+        "url": "https://catfact.ninja",\
+        "description": "Production server"\
+      }\
+    ],\
+    "paths": {\
+      "/fact": {\
+        "get": {\
+          "summary": "Get a random cat fact",\
+          "description": "Returns a random cat fact.",\
+          "responses": {\
+            "200": {\
+              "description": "Successful response",\
+              "content": {\
+                "application/json": {\
+                  "schema": {\
+                    "$ref": "#/components/schemas/Fact"\
+                  }\
+                }\
+              }\
+            }\
+          }\
+        }\
+      }\
+    },\
+    "components": {\
+      "schemas": {\
+        "Fact": {\
+          "type": "object",\
+          "properties": {\
+            "fact": {\
+              "type": "string",\
+              "description": "The cat fact"\
+            }\
+          }\
+        }\
+      }\
+    }\
+  }';
+
+  beforeEach(() => {
+    instance = new OpenAPITool({
+      name: "Cat Facts",
+      description: "A simple API for cat facts",
+      openApiSchema: cat_spec,
+    });
+  });
+
+  it("Runs", async () => {
+    const response = await instance.run(
+      {
+        path: "/fact",
+        method: "get",
+      },
+      {
+        signal: AbortSignal.timeout(60 * 1000),
+        retryOptions: {},
+      },
+    );
+
+    expect(response.isEmpty()).toBe(false);
+  });
+});

yarn.lock

@@ -4915,6 +4915,7 @@ __metadata:
     openai: ^4.67.3
     openai-chat-tokens: ^0.2.8
     sequelize: ^6.37.3
+    yaml: ^2.6.1
   peerDependenciesMeta:
     "@aws-sdk/client-bedrock-runtime":
       optional: true
@@ -4948,6 +4949,8 @@ __metadata:
       optional: true
     sequelize:
       optional: true
+    yaml:
+      optional: true
   languageName: unknown
   linkType: soft