Create JavaScript Plugins

Creating a Plugin

Plugin Interface

Every plugin must implement the Plugin interface:

export interface Plugin {
  name: string;
  version?: string;
  description?: string;
  tools: (context: Context) => Tool[];
}

Tool Interface

Each tool must implement the Tool interface:

export type Tool = {
  method: string;
  name: string;
  description: string;
  parameters: z.ZodObject<any, any>;
  execute: (client: Client, context: Context, params: any) => Promise<any>;
  // transactionToolOutputParser and untypedQueryOutputParser can be used. If required, define a custom parser
  outputParser?: (rawOutput: string) => { raw: any; humanMessage: string };
};

See packages/core/src/shared/tools.ts for the full definition.

BaseTool (Recommended for v4)

This is NOT a breaking change. BaseTool is an abstract class that implements the Tool interface — plain object tools continue to work exactly as before. However, they do not support the hooks and policies system introduced in v4 (e.g., HcsAuditTrailHook, MaxRecipientsPolicy, RejectToolPolicy). To enable those features, migrate your tool to BaseTool.

Extending BaseTool splits execution into a 7-stage lifecycle that hooks and policies tap into automatically — you never call them manually. For a detailed step-by-step guide on refactoring your tools, see the Migration Guide.

import type { Tool } from '@/shared/tools';

const tool = (context: Context): Tool => ({
  method: MY_TOOL,
  name: 'My Tool',
  description: myToolPrompt(context),
  parameters: myToolParameters(context),
  execute: myToolExecute, // all logic in one function; no hook/policy entry points
});

export default tool;

import { BaseTool } from '@/shared/tools'; // BaseTool implements Tool

export class MyTool extends BaseTool {
  method = MY_TOOL;
  name = 'My Tool';
  description: string;
  parameters: ReturnType<typeof myToolParameters>;
  outputParser = myOutputParser; // optional

  constructor(context: Context) {
    super();
    this.description = myToolPrompt(context);
    this.parameters = myToolParameters(context);
  }

  // Stage 2: normalize/validate params
  async normalizeParams(params: any, context: Context, client: Client) {
    return await MyNormaliser.normalise(params, context, client);
  }

  // Stage 4: build tx or run query
  async coreAction(normalisedParams: any, _context: Context, _client: Client) {
    return MyBuilder.buildTx(normalisedParams);
  }

  // Stage 6: sign and submit (override shouldSecondaryAction() to skip for query-only tools)
  async secondaryAction(transaction: any, client: Client, context: Context) {
    return await handleTransaction(transaction, client, context, postProcess);
  }

  // Optional: custom error handling (BaseTool provides a sensible default)
  async handleError(error: unknown, _context: Context) {
    const msg = `Failed: ${error instanceof Error ? error.message : error}`;
    return { raw: { error: msg }, humanMessage: msg };
  }
}

const tool = (context: Context): BaseTool => new MyTool(context);
export default tool;

	v3 (`Tool` object)	v4 (`BaseTool` class)
Import	`import type { Tool }`	`import { BaseTool }`
Declaration	Object literal	Class extending `BaseTool`
Lifecycle	Single `execute()`	`normalizeParams` → `coreAction` → `secondaryAction`
Hooks & policies	✗ None	✓ Automatic at stages 1, 3, 5, 7
Error handling	Manual `try/catch` in `execute`	Override `handleError()`
Breaking change	—	No

Step-by-Step Guide

Step 1: Create Plugin Directory Structure

  my-custom-plugin/
  ├── index.ts                    # Plugin definition and exports
  ├── tools/
  │   └── my-service/
  │       └── my-tool.ts         # Individual tool implementation

Step 2: Implement Your Tool

Create your tool file (e.g., tools/my-service/my-tool.ts):

This example uses Hedera Agent Kit v4 which extends the BaseTool class to enable policies & hooks

import { z } from "zod";
import { Context, BaseTool, handleTransaction } from "@hashgraph/hedera-agent-kit";
import { Client } from "@hiero-ledger/sdk";

// Define parameter schema
const myToolParameters = (context: Context = {}) =>
  z.object({
    requiredParam: z.string().describe("Description of required parameter"),
    optionalParam: z
      .string()
      .optional()
      .describe("Description of optional parameter"),
  });

// Create prompt function
const myToolPrompt = (context: Context = {}) => `
  This tool performs a specific operation.

  Parameters:
  - requiredParam (string, required): Description
  - optionalParam (string, optional): Description
`;

export const MY_TOOL = "my_tool";

export class MyCustomTool extends BaseTool {
  method = MY_TOOL;
  name = "My Custom Tool";
  description: string;
  parameters: ReturnType<typeof myToolParameters>;

  constructor(context: Context) {
    super();
    this.description = myToolPrompt(context);
    this.parameters = myToolParameters(context);
  }

  // Stage 2: normalize/validate params before core logic runs
  async normalizeParams(
    params: z.infer<ReturnType<typeof myToolParameters>>,
    _context: Context,
    _client: Client,
  ) {
    return params; // transform or enrich params here if needed
  }

  // Stage 4: build the transaction or run the query
  async coreAction(normalisedParams: any, _context: Context, _client: Client) {
    return await someHederaOperation(normalisedParams);
  }

  // Stage 6: sign and submit (omit or override shouldSecondaryAction() for query-only tools)
  async secondaryAction(result: any, client: Client, context: Context) {
    return await handleTransaction(result, client, context);
  }

  // Optional: override for tool-specific error messages
  async handleError(error: unknown, _context: Context) {
    const msg = `Operation failed: ${error instanceof Error ? error.message : error}`;
    return { raw: { error: msg }, humanMessage: msg };
  }
}

const tool = (context: Context): BaseTool => new MyCustomTool(context);
export default tool;

Step 3: Create Plugin Definition

Create your plugin index file (index.ts):

  import { Context, Plugin } from '@hashgraph/hedera-agent-kit';
  import myTool, { MY_TOOL } from './tools/my-service/my-tool';

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

  export const myCustomPluginToolNames = {
    MY_TOOL,
  } as const;

  export default { myCustomPlugin, myCustomPluginToolNames };

Best Practices

Parameter Validation

Use Zod schemas for robust input validation
Provide clear descriptions for all parameters
Mark required vs optional parameters appropriately

Tool Organization

Group related tools by service type
Use consistent naming conventions
Follow the established directory structure

Transaction Handling

Use handleTransaction() to facilitate human-in-the-loop and autonomous execution flows
Respect the AgentMode (AUTONOMOUS vs RETURN_BYTES)
Implement proper transaction building patterns

Tool Output Parsing

The Hedera Agent Kit tools return a structured JSON output. Each tool returns:

{
  raw: any;          // The raw data returned by the tool (e.g., transaction receipt, query result)
  humanMessage: string; // A human-readable message describing the result
}

This allows you to easily display a user-friendly message while still having access to the raw data for further processing.

Using Your Custom Plugin

import { Client, PrivateKey } from "@hiero-ledger/sdk";
import { AgentMode } from "@hashgraph/hedera-agent-kit";
import { myCustomPlugin } from "./plugins/my-custom-plugin";
import { HederaLangchainToolkit } from "@hashgraph/hedera-agent-kit-langchain";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";

const client = Client.forTestnet().setOperator(
  process.env.ACCOUNT_ID!,
  PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY!),
);

const toolkit = new HederaLangchainToolkit({
  client,
  configuration: {
    plugins: [myCustomPlugin],
    context: {
      mode: AgentMode.AUTONOMOUS,
    },
  },
});

const tools = toolkit.getTools();

const prompt = ChatPromptTemplate.fromMessages([
  ['system', 'You are a helpful assistant with access to Hedera blockchain tools'],
  ['human', '{input}'],
  ['placeholder', '{agent_scratchpad}'],
]);

const agent = createToolCallingAgent({ llm, tools, prompt });

const agentExecutor = new AgentExecutor({ agent, tools });

const response = await agentExecutor.invoke({ input: "what's my balance?" });

console.log(response?.output ?? response);

Examples and References

See existing core plugins in typescript/src/plugins/core-*-plugin/
Follow the patterns established in tools like transfer-hbar.ts
See typescript/examples/langchain-v1/plugin-tool-calling-agent.ts for usage examples

Publish and Register Your Plugin

To create a plugin to be used with the Hedera Agent Kit, you will need to create a plugin in your own repository, publish a npm package, and provide a description of the functionality included in that plugin, as well as the required and optional parameters. Once you have a repository, published npm package, and a README with a description of the functionality included in that plugin in your plugin’s repo, as well as the required and optional parameters, you can add it to the Hedera Agent Kit by forking and opening a Pull Request to:

Include the plugin as a bullet point under the Available Third Party Plugin section under the Third Party Plugin section in the README.md in the hedera-agent-kit-js. Include the name, a brief description, and a link to the repository with the README, as well the URL linked to the published npm package.
If you would like to include your plugin functionality in the Hedera plugin built for ElizaOS simply make a PR to add your plugin name to the plugins array in the Hedera ElizaOS plugin where the configuration is initiated. The hedera-agent-kit adaptor architecture means your plugin functionality will be usable with no additional configuration needed.
All commits for your plugin must be DCO signed, have the names of the tools & core actions exposed by the plugin, and point to the exact version of the npm packages. To avoid having pull requests blocked in the future, always include a sign-off:

Plugin is a unified SDK to the Bonzo protocol, exposing the core actions (deposit, withdraw, repay, borrow) for decentralised lending and borrowing on Hedera:

NPM: https://www.npmjs.com/package/@bonzofinancelabs/hak-bonzo-plugin
Github repository: https://github.com/Bonzo-Labs/bonzoPlugin
Version: @bonzofinancelabs/hak-bonzo-plugin@1.0.1
Status: Not validated by HAK team, v3-compatible release 

Feel free to also reach out to the Hedera Agent Kit maintainers on Discord or another channel so we can test out your plugin, include it in our docs, and let our community know thorough marketing and community channels. Please also reach out in the Hedera Discord in the Support > developer-help-desk channel create an Issue in this repository for help building, publishing, and promoting your plugin

Plugin README Template

## Plugin Name

This plugin was built by <?> for the <project, platform, etc>. It was built to enable <who?> to <do what?>

<Include a description of your project and how it can be used with the Hedera Agent Kit.>

### Installation

'''bash
npm install <plugin-name>
'''

### Usage

'''javascript
import { myPlugin } from "<plugin-name>";
'''

'''typescript
import { AgentMode } from '@hashgraph/hedera-agent-kit';
import { myPlugin } from '<plugin-name>';
import { HederaLangchainToolkit } from '@hashgraph/hedera-agent-kit-langchain';

const hederaAgentToolkit = new HederaLangchainToolkit({
    client,
    configuration: {
        context: {
            mode: AgentMode.AUTONOMOUS,
        },
        plugins: [myPlugin],
    },
});

const tools = toolkit.getTools();
'''

### Functionality

Describe the different tools or individual pieces of functionality included in this plugin, and how to use them.

**Plugin Name**
_High level description of the plugin_

| Tool Name               | Description  | Usage                                                           |
| ----------------------- | ------------ | --------------------------------------------------------------- |
| `YOUR_PLUGIN_TOOL_NAME` | What it does | How to use. Include a list of parameters and their descriptions |

Resources

GitHub: https://github.com/hashgraph/hedera-agent-kit-js
Discord: https://hedera.com/discord

Examples and References

See existing core plugins in the hedera agent kit examples
Follow the patterns established in tools like transfer-hbar.ts
See typescript/examples/langchain/tool-calling-agent.ts for usage examples

​Creating a Plugin

​Plugin Interface

​Tool Interface

​BaseTool (Recommended for v4)

​Step-by-Step Guide

​Step 1: Create Plugin Directory Structure

​Step 2: Implement Your Tool

​Step 3: Create Plugin Definition

​Best Practices

​Tool Output Parsing

​Using Your Custom Plugin

​Examples and References

​Publish and Register Your Plugin

​Plugin README Template

​Resources

​Examples and References

Creating a Plugin

Plugin Interface

Tool Interface

BaseTool (Recommended for v4)

Step-by-Step Guide

Step 1: Create Plugin Directory Structure

Step 2: Implement Your Tool

Step 3: Create Plugin Definition

Best Practices

Tool Output Parsing

Using Your Custom Plugin

Examples and References

Publish and Register Your Plugin

Plugin README Template

Resources

Examples and References