This example demonstrates how to create a basic Atomemo plugin with a simple tool that performs a calculation.
Overview
You’ll learn how to:
- Initialize a plugin with
createPlugin()
- Define a basic tool using
addTool()
- Implement the tool’s
invoke function
- Run the plugin process
Complete Example
import { createPlugin } from "@choiceopen/atomemo-plugin-sdk-js";
import { z } from "zod";
const plugin = await createPlugin({
name: "math-toolkit",
display_name: { en_US: "Math Toolkit" },
description: { en_US: "A simple plugin with basic math operations" },
icon: "🔢",
locales: ["en_US"],
});
// Define a calculator tool
plugin.addTool({
name: "calculate",
display_name: { en_US: "Calculate" },
description: { en_US: "Perform basic arithmetic calculations" },
icon: "🧮",
parameters: [
{
name: "operation",
display_name: { en_US: "Operation" },
description: { en_US: "The arithmetic operation to perform" },
type: "string",
required: true,
enum: ["add", "subtract", "multiply", "divide"],
},
{
name: "a",
display_name: { en_US: "First Number" },
description: { en_US: "The first operand" },
type: "number",
required: true,
},
{
name: "b",
display_name: { en_US: "Second Number" },
description: { en_US: "The second operand" },
type: "number",
required: true,
},
],
invoke: async ({ args }) => {
const { operation, a, b } = args.parameters;
let result: number;
switch (operation) {
case "add":
result = a + b;
break;
case "subtract":
result = a - b;
break;
case "multiply":
result = a * b;
break;
case "divide":
if (b === 0) {
throw new Error("Cannot divide by zero");
}
result = a / b;
break;
default:
throw new Error(`Unknown operation: ${operation}`);
}
return {
result,
message: `${a} ${operation} ${b} = ${result}`,
};
},
});
// Start the plugin process
await plugin.run();
Code Breakdown
Plugin Initialization
The plugin is created using createPlugin() with metadata:
const plugin = await createPlugin({
name: "math-toolkit", // Unique plugin identifier
display_name: { en_US: "Math Toolkit" }, // Human-readable name
description: { en_US: "A simple plugin..." },
icon: "🔢", // Plugin icon (emoji or URL)
locales: ["en_US"], // Supported locales
});
The createPlugin() function is async because it fetches user session information in debug mode.
- Metadata: Name, display name, description, and icon
- Parameters: Input schema with type validation
- Invoke function: The actual implementation
plugin.addTool({
name: "calculate",
// ... metadata
parameters: [
{
name: "operation",
type: "string",
required: true,
enum: ["add", "subtract", "multiply", "divide"],
},
// ... more parameters
],
invoke: async ({ args }) => {
// Implementation here
},
});
Invoke Function
The invoke function receives an object with:
args.parameters: The input parameters from the userargs.credentials: Any credentials needed (see tool-with-credentials)
invoke: async ({ args }) => {
const { operation, a, b } = args.parameters;
// Perform the operation and return results
return { result, message };
}
Running the Plugin
The run() method starts the plugin process:
This:
- Establishes a connection with the Atomemo platform
- Registers the plugin and its tools
- Listens for tool invocation requests
- Handles graceful shutdown on SIGINT/SIGTERM
Running the Plugin
Set up environment
Create a .env file with the required configuration:HUB_MODE=debug
HUB_WS_URL=wss://api.atomemo.ai/socket
Next Steps
Tool with Credentials
Learn how to add authentication to your tools
Custom Model
Add custom AI models to your plugin