Creating Hedera Agent Kit Plugins

This skill provides guidance for creating custom plugins that extend the Hedera Agent Kit. Plugins allow adding new tools for Hedera network interactions—token operations, account management, consensus service, smart contracts, and custom integrations.

Quick Start

To create a Hedera plugin in 5 steps:

1. Install dependencies: Set up a TypeScript project with hedera-agent-kit and @hashgraph/sdk
2. Create plugin structure: Create an index.ts with the plugin definition and a tools/ directory
3. Define tools: Create tool files with method, name, description, parameters, and execute function
4. Export properly: Export the plugin object and tool name constants
5. Register with agent: Import and register the plugin with PluginRegistry

Plugin Interface

Every Hedera plugin implements this interface from hedera-agent-kit:

import { Plugin } from 'hedera-agent-kit';

export interface Plugin {
  name: string;           // Unique kebab-case identifier
  version?: string;       // Semantic version (e.g., "1.0.0")
  description?: string;   // Brief explanation of plugin purpose
  tools: (context: Context) => Tool[];  // Factory returning tools
}

The tools function receives a Context object containing network configuration and returns an array of Tool objects.

Tool Interface

Each tool implements this interface:

import { Tool } from 'hedera-agent-kit';

export interface Tool {
  method: string;           // Unique snake_case identifier (e.g., "create_token_tool")
  name: string;             // Human-readable display name
  description: string;      // LLM-friendly description for the AI agent
  parameters: z.ZodObject;  // Zod schema for input validation
  execute: (client: Client, context: Context, params: any) => Promise<any>;
  outputParser?: (rawOutput: string) => { raw: any; humanMessage: string };
}

Tool Types

Mutation Tools - Perform state-changing operations:

• Token creation, minting, transfers
• Account creation, updates
• Topic creation, message submission
• Use handleTransaction() for execution
• Use transactionToolOutputParser for output

Query Tools - Read data without state changes:

• Token info, balances
• Account details
• Topic messages
• Direct service calls
• Use untypedQueryOutputParser for output

File Structure Pattern

Follow this structure for all Hedera plugins:

my-hedera-plugin/
├── index.ts                    # Plugin definition and exports
└── tools/
    └── category/               # Group related tools
        ├── create-something.ts
        └── get-something.ts

Creating a Tool

Step 1: Define the Tool Constant

export const MY_TOOL_NAME = 'my_tool_name_tool';

Use UPPER_SNAKE_CASE with _TOOL suffix for the constant. The value should be lowercase snake_case.

Step 2: Create the Prompt Function

const myToolPrompt = (context: Context = {}) => {
  return `This tool does X on Hedera.
Parameters:
- param1 (str, required): Description of param1
- param2 (int, optional): Description of param2, defaults to 0`;
};

Descriptions guide the AI agent on when and how to use the tool. Be specific about parameter types and requirements.

Step 3: Define Parameters with Zod

import { z } from 'zod';

const myToolParameters = (context: Context = {}) => {
  return z.object({
    param1: z.string().describe('Description of param1'),
    param2: z.number().optional().describe('Description of param2'),
  });
};

See references/zod-schema-patterns.md for common Hedera parameter patterns.

Step 4: Implement the Execute Function

const myToolExecute = async (
  client: Client,
  context: Context,
  params: z.infer<ReturnType<typeof myToolParameters>>,
) => {
  try {
    // Build and execute Hedera transaction
    const result = await handleTransaction(tx, client, context, postProcess);
    return result;
  } catch (error) {
    const message = 'Failed to execute' + (error instanceof Error ? `: ${error.message}` : '');
    return { raw: { error: message }, humanMessage: message };
  }
};

Step 5: Create the Tool Factory

const tool = (context: Context): Tool => ({
  method: MY_TOOL_NAME,
  name: 'My Tool Display Name',
  description: myToolPrompt(context),
  parameters: myToolParameters(context),
  execute: myToolExecute,
  outputParser: transactionToolOutputParser,
});

export default tool;

Creating the Plugin Index

import { Context } from 'hedera-agent-kit';
import { Plugin } from 'hedera-agent-kit';
import myTool, { MY_TOOL_NAME } from './tools/category/my-tool';

export const myPlugin: Plugin = {
  name: 'my-hedera-plugin',
  version: '1.0.0',
  description: 'A plugin for custom Hedera operations',
  tools: (context: Context) => {
    return [
      myTool(context),
    ];
  },
};

export const myPluginToolNames = {
  MY_TOOL_NAME,
} as const;

export default { myPlugin, myPluginToolNames };

Post-Processing Results

Create human-readable output from transaction results:

const postProcess = (response: RawTransactionResponse) => {
  if (response.scheduleId) {
    return `Scheduled transaction created.
Transaction ID: ${response.transactionId}
Schedule ID: ${response.scheduleId.toString()}`;
  }
  return `Operation completed.
Transaction ID: ${response.transactionId}
Result: ${response.someValue}`;
};

Naming Conventions

Element	Convention	Example
Plugin name	kebab-case	my-token-plugin
Plugin variable	camelCase	myTokenPlugin
Tool constant	UPPER_SNAKE_CASE + _TOOL	CREATE_TOKEN_TOOL
Tool method value	snake_case + _tool	create_token_tool
Tool file	kebab-case	create-token.ts
Tool names export	camelCase + ToolNames	myTokenPluginToolNames

Common Imports

// From hedera-agent-kit
import { Context } from 'hedera-agent-kit';
import { Plugin } from 'hedera-agent-kit';
import { Tool } from 'hedera-agent-kit';
import { handleTransaction, RawTransactionResponse } from 'hedera-agent-kit';
import { transactionToolOutputParser, untypedQueryOutputParser } from 'hedera-agent-kit';

// From Hedera SDK
import { Client, Status } from '@hashgraph/sdk';

// For parameter validation
import { z } from 'zod';

Additional Resources

Reference Files

For detailed patterns and techniques, consult:

• references/plugin-interface.md - Complete Plugin and Tool interface documentation
• references/zod-schema-patterns.md - Common Zod schemas for Hedera parameters
• references/prompt-patterns.md - Prompt generation patterns for tool descriptions
• references/error-handling.md - Error handling and output parsing patterns

Example Files

Working examples in examples/:

• examples/simple-plugin/ - Basic plugin with one tool (starter template)
• examples/token-plugin/ - Full token plugin with mutation and query tools

Best Practices

1. Group related tools: Use category directories under tools/
2. Consistent naming: Follow the naming conventions strictly
3. Clear descriptions: Write prompts that help the AI understand when to use the tool
4. Validate inputs: Use Zod schemas with descriptive .describe() calls
5. Handle errors: Always catch errors and return structured error responses
6. Human-readable output: Use postProcess to format results for users
7. Export tool names: Allow consumers to reference tools programmatically

Registering Plugins

After creating a plugin, register it with the Hedera Agent Kit:

import { PluginRegistry } from 'hedera-agent-kit';
import { myPlugin } from './my-hedera-plugin';

const registry = new PluginRegistry();
registry.register(myPlugin);

// Get all tools from registered plugins
const tools = registry.getTools(context);

Workflow Summary

1. Create plugin directory with index.ts and tools/ subdirectory
2. Create tool files following the 5-step pattern
3. Export tools from plugin index with tool name constants
4. Register plugin with PluginRegistry
5. Tools become available to the AI agent

For complete working examples, see the examples/ directory.