@radiustechsystems/ai-agent-core NPM

Radius AI Agent Toolkit - Core

Core abstractions and base classes for the Radius AI Agent Toolkit. This package provides the foundation for building AI agent tools and plugins for interacting with the Radius platform.

This package is part of the Radius AI Agent Toolkit, which provides tools for integrating AI agents with the Radius platform.

Installation

# Install this specific package
npm install @radiustechsystems/ai-agent-core

# Peer dependencies
npm install zod reflect-metadata

Prerequisites

Node.js >=20.12.2 <23
TypeScript configuration with:
- experimentalDecorators: true
- emitDecoratorMetadata: true

Example tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    // ... other options
  }
}

Usage

The core package provides base classes and decorators for building AI agent tools and plugins:

import { PluginBase, Tool, createToolParameters } from "@radiustechsystems/ai-agent-core";
import { z } from "zod";

// First, create parameter types using createToolParameters
const MyToolParams = createToolParameters(
  z.object({
    param1: z.string().describe("A string parameter"),
    param2: z.number().describe("A number parameter")
  })
);

// Create service class that implements the tool logic
class MyService {
  @Tool({
    description: "Does something useful"
  })
  async myCustomTool(params: MyToolParams): Promise<string> {
    // Tool implementation
    return `Processed ${params.param1} with value ${params.param2}`;
  }
}

// Create a custom plugin by extending PluginBase
class MyCustomPlugin extends PluginBase {
  private service: MyService;
  
  constructor() {
    // Pass the name and tool providers to the parent constructor
    const service = new MyService();
    super("my_custom_plugin", [service]);
    this.service = service;
  }
  
  // Implement required abstract method
  supportsChain(chain: any): boolean {
    // For simplicity, support all chains in this example
    return true;
  }
}

// Create a mock wallet client (simplified for example)
class MockWalletClient {
  getAddress() { return "0x..."; }
  getChain() { return { type: "evm", id: 1 }; }
  // Other required wallet methods
}

// Create an instance of your plugin
const myPlugin = new MyCustomPlugin();
const walletClient = new MockWalletClient();

// Get all tools from the plugin (passing required wallet client)
const tools = myPlugin.getTools(walletClient);

// Execute a tool
if (tools.length > 0) {
  const result = await tools[0].execute({
    param1: "test-string",
    param2: 42
  });
  console.log(result); // "Processed test-string with value 42"
}

API Reference

Base Classes

`PluginBase`

Abstract base class for creating Radius AI agent plugins. Plugins provide a way to organize related tools.

Constructor:

constructor(name: string, toolProviders: object[]): Creates a new plugin with the given name and tool providers

Properties:

name: The name of the plugin
toolProviders: Array of objects that provide tools (using the @Tool decorator)

Methods:

getTools(walletClient: WalletClientBase): Returns all tools defined in the plugin
supportsChain(chain: Chain): Abstract method that must be implemented to check if the plugin supports a chain

`ToolBase`

Base class for creating standalone AI agent tools. Tools created with this class can be used directly without a plugin.

Constructor:

constructor(options: { name: string; description: string; parameters: z.ZodSchema }, executeFunction: (params: any) => Promise<any>): Creates a new tool

Properties:

name: The name of the tool
description: Description of what the tool does
parameters: Zod schema defining the tool's parameters

Methods:

execute(params: unknown): Executes the tool with the given parameters

Factory Function:

The createTool function can be used to create a new ToolBase instance:

import { createTool } from "@radiustechsystems/ai-agent-core";
import { z } from "zod";

const myTool = createTool(
  {
    name: "my_tool",
    description: "Does something useful",
    parameters: z.object({
      value: z.string().describe("A parameter")
    })
  },
  async (params) => {
    // Tool implementation
    return `Processed ${params.value}`;
  }
);

Decorators

`@Tool(params)`

Decorator for marking methods as AI agent tools.

Parameters:

params.name (string, optional): The name of the tool (defaults to the method name in snake_case)
params.description (string): Description of what the tool does

Utility Functions

`createToolParameters(schema)`

Creates a class with a static schema property that can be used as a parameter type for tools.

Parameters:

schema (z.ZodSchema): Zod schema defining the tool's parameters

Returns:

A class that can be used as a parameter type for tools

Example:

import { createToolParameters } from "@radiustechsystems/ai-agent-core";
import { z } from "zod";

// Create parameter type
const MyParams = createToolParameters(
  z.object({
    name: z.string().describe("The name parameter"),
    value: z.number().describe("The value parameter")
  })
);

// Use in a tool method
@Tool({
  description: "Example tool"
})
async myTool(params: MyParams): Promise<string> {
  // Params are fully typed
  return `Name: ${params.name}, Value: ${params.value}`;
}