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}`;
}

Integration Examples

For complete examples integrating this package with AI frameworks, see:

• Vercel AI Micropayments Example

Related Packages

• @radiustechsystems/ai-agent-wallet: Wallet functionality for interacting with blockchain
• @radiustechsystems/ai-agent-adapter-vercel-ai: Adapter for Vercel AI SDK integration
• @radiustechsystems/ai-agent-plugin-erc20: Plugin for ERC20 token interactions

Resources

• Website
• Testnet Access
• GitHub Issues
• Changelog

Contributing

Please see the Contributing Guide for detailed information about contributing to this toolkit.

License

This project is licensed under the MIT License.