Radius AI Agent Toolkit - Contracts Plugin

This plugin enables AI agents to interact with any smart contract on Radius through a standardized interface, allowing them to call read-only methods and execute state-changing contract functions.

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-plugin-contracts

# Required peer dependencies
npm install @radiustechsystems/ai-agent-core
npm install @radiustechsystems/ai-agent-wallet
npm install viem

Prerequisites

• Node.js >=20.12.2 <23
• Radius wallet setup with a funded account
• Smart contract ABI definitions for contracts you wish to interact with

Usage

import { contracts } from "@radiustechsystems/ai-agent-plugin-contracts";
import { createRadiusWallet } from "@radiustechsystems/ai-agent-wallet";
import { getOnChainTools } from "@radiustechsystems/ai-agent-adapter-vercel-ai";

// Create a Radius wallet
const wallet = await createRadiusWallet({
  rpcUrl: process.env.RPC_PROVIDER_URL,
  privateKey: process.env.WALLET_PRIVATE_KEY
});

// Initialize the Contracts plugin
const contractsPlugin = contracts();

// Create AI agent tools with the Contracts plugin
const tools = await getOnChainTools({
  wallet,
  plugins: [contractsPlugin]
});

Example: Interacting with a Contract

// Example of using the contracts plugin through an AI agent
const result = await generateText({
  model: openai("gpt-4o"),
  tools,
  maxSteps: 10,
  prompt: `Call the 'balanceOf' function on the contract at address 0x1234... 
           using this ABI: [{"inputs":[{"name":"account","type":"address"}],"name":"balanceOf","outputs":[{"name":"","type":"uint256"}],"stateMutability":"view","type":"function"}]
           Check the balance of address 0x5678...`,
});

// The AI will use the call_contract tool to execute this request

API Reference

contracts()

Creates a new Contracts plugin instance.

Returns:

• A ContractsPlugin instance that can be used with AI agent frameworks

Provided Tools

The Contracts plugin provides the following AI agent tools:

call_contract

Calls a read-only method on a smart contract and returns the result.

Parameters:

• contractAddress (string): The address of the contract
• abi (array): The ABI of the contract
• functionName (string): The name of the function to call
• args (array, optional): The arguments to pass to the function

Example:

try {
  const result = await callContractTool.execute({
    contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC contract
    abi: erc20Abi,
    functionName: "symbol",
    args: []
  });
  console.log(`Contract call result: ${result}`);
} catch (error) {
  console.error(`Contract call failed: ${error.message}`);
}

execute_contract

Executes a state-changing method on a smart contract.

Parameters:

• contractAddress (string): The address of the contract
• abi (array): The ABI of the contract
• functionName (string): The name of the function to execute
• args (array, optional): The arguments to pass to the function
• value (string, optional): The amount of ETH to send with the transaction

Example:

try {
  const txResult = await executeContractTool.execute({
    contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC contract
    abi: erc20Abi,
    functionName: "transfer",
    args: ["0x...", "1000000"] // recipient, amount
  });
  console.log(`Transaction hash: ${txResult.hash}`);
} catch (error) {
  console.error(`Transaction failed: ${error.message}`);
}

simulate_contract

Simulates a contract interaction without submitting a transaction.

Parameters:

• contractAddress (string): The address of the contract
• abi (array): The ABI of the contract
• functionName (string): The name of the function to simulate
• args (array, optional): The arguments to pass to the function
• value (string, optional): The amount of ETH to send with the transaction

Example:

try {
  const simulationResult = await simulateContractTool.execute({
    contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC contract
    abi: erc20Abi,
    functionName: "transfer",
    args: ["0x...", "1000000"] // recipient, amount
  });
  console.log(`Simulation result:`, simulationResult);
} catch (error) {
  console.error(`Simulation failed: ${error.message}`);
}

Note on Tool Naming: The tool names in this documentation (call_contract, execute_contract, simulate_contract) match the actual names used at runtime. The @Tool decorator in the implementation automatically converts camelCase method names to snake_case for the final tool names.

Integration Examples

For a complete example integrating this plugin with AI frameworks, see:

• Micropayments Example

Related Packages

• @radiustechsystems/ai-agent-core: Core abstractions and base classes
• @radiustechsystems/ai-agent-wallet: Wallet functionality
• @radiustechsystems/ai-agent-plugin-erc20: ERC20 token operations

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.