Create a Plugin

Introduction

Before creating a plugin, ensure you have completed the advanced setup process. Plugins are powerful extensions that expand an agent's capabilities by adding custom tools. These tools allow agents to perform specialized tasks and access additional functionality beyond their base capabilities.

Create a new plugin using the Open Agent Kit CLI:

npx @open-agent-kit/cli create plugin

This will generate a plugin template with a sample tool implementation. The CLI will guide you through the setup process and create all necessary files and folders.

This will create the plugin template and comes with a sample tool.

Plugin Structure

Routes

With custom routes, you can create the UI for your plugin. This can be used to describe functionalities and provide a space for plugin configuration. Retrieve and store configuration is done via the OAKProvider with the functions getPluginConfig and setPluginConfig.

Below is an example of how you might set up a route:

// routes/_index.tsx
import React from "react";
import { oak } from "../provider";
import { Form, useActionData, useLoaderData } from "react-router";

export const action = async ({ request, params }) => {
  const formData = await request.formData();
  const agentId = params.agentId as string;
  const min = formData.get("min");
  const max = formData.get("max");
  await oak.setPluginConfig(agentId, { min, max });
  return { success: true };
};

export const loader = async ({ params }) => {
  const agentId = params.agentId as string;
  const config = await oak.getPluginConfig(agentId);
  return { config };
};

export default () => {
  const actionData = useActionData();
  const { config } = useLoaderData();
  return (
    <div>
      <h2>Sample Plugin Configuration</h2>
      <Form method="post">
        <input type="number" defaultValue={config?.min} name="min" />
        <input type="number" defaultValue={config?.max} name="max" />
        <button type="submit">Save Configuration</button>
      </Form>
      {actionData?.success && <div>Configuration updated successfully!</div>}
    </div>
  );
};

Tools

Tools are specialized functions or modules that extend the capabilities of AI language models by performing tasks beyond text generation, such as fetching data, performing calculations, or interacting with external systems.

A language model (LLM) can call tools based on input context to provide more accurate or relevant responses. The model generates a "tool call" when it determines a tool can enhance its response, using the tool's output to form the final answer.

The AI SDK comes with several built-in default tools that enhance the capabilities of language models. These tools include the dateTimeAndDay tool, a feedback tool, and a knowledgeBase tool.

To maximize the effectiveness of tools within the AI SDK, it's crucial to understand their implementation and integration. Tools can be invoked by the language model to improve responses based on the input context. For detailed instructions on utilizing tools, consult the AI SDK Core documentation on tools and tool calling.

After creating a tool, ensure it is added to the tools array in the config.server.ts file. Refer to the Configure Plugin section for more details.

Below is an example of a tool implementation:

// tools/randomNumber.ts
import { tool } from "ai";
import { oak } from "../provider";

const generateRandomNumber = ({ agentId }) =>
  tool({
    description: "Generate a random number",
    execute: async () => {
      const config = await oak.getPluginConfig(agentId);
      const min = config?.min ?? 0;
      const max = config?.max ?? 100;
      const gen = Math.floor(Math.random() * (max - min + 1)) + min;
      return { min, max, generatedNumber: gen };
    },
  });

export default {
  identifier: "randomNumber",
  name: "Random Number",
  tool: generateRandomNumber,
};

Tool Components

Tool components can be used in addition to the LLM text response to visualize the tool response individually. Be sure to name the toolComponent file the same as the tool's identifier.

Below is an example of a tool component:

// toolComponent/randomNumber.tsx
import React from "react";

export default (props) => (
  <div>
    Generating a random number 🧙‍♂️.
    {props.result?.generatedNumber && (
      <span>
        The wizard has generated a random number: {props.result.generatedNumber}
      </span>
    )}
  </div>
);

Configure Plugin

In the config.server.ts file, you configure plugin metadata and set the available tools in the tools array. The menuItems array allows you to add quick links to plugin routes in the side menu of the admin interface.

import type { PluginConfig } from "@open-agent-kit/core/app/types/plugins";
import routes from "./routes";
import randomNumber from "./tools/randomNumber";

const config = {
  description: "description",
  slug: "sample",
  displayName: "sample",
  routes: routes,
  // menuItems: [
  //   {
  //     label: "Oak Sample Plugin",
  //     href: "/",
  //     icon: "Codesandbox",
  //   },
  // ],
  tools: [randomNumber],
} satisfies PluginConfig;

export default config;