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:

Install dependencies: Set up a TypeScript project with
```
@hashgraph/hedera-agent-kit
```
and
```
@hiero-ledger/sdk
```
Create plugin structure: Create an
```
index.ts
```
with the plugin definition and a
```
tools/
```
directory
Define tools: Each tool is a class extending
```
BaseTool
```
— this opts the tool into the hooks/policies lifecycle
Export properly: Export the plugin object and tool name constants
Register with agent: Import and pass the plugin in the toolkit
```
configuration.plugins
```
array

Plugin Interface

Every Hedera plugin implements this interface from

@hashgraph/hedera-agent-kit

typescript

import { Plugin } from '@hashgraph/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.

BaseTool

itself implements

Tool

, so a

BaseTool

subclass instance is a valid return value.

BaseTool

Tools are written as classes extending

BaseTool

, which implements

Tool

and runs a 7-stage lifecycle:

text

[1] preToolExecutionHook
[2] normalizeParams        ← your logic
[3] postParamsNormalizationHook
[4] coreAction             ← your logic
[5] postCoreActionHook
[6] secondaryAction        ← your logic (skipped via shouldSecondaryAction for queries)
[7] postToolExecutionHook

Hooks and policies registered on the agent kit fire at stages 1, 3, 5, and 7 automatically — you never call them manually.

A subclass must provide:

Member	Type	Notes
`method`	`string`	Snake-case identifier with `_tool` suffix
`name`	`string`	Human-readable display name
`description`	`string`	LLM-facing description (typically built in the constructor from a prompt function)
`parameters`	`z.ZodObject`	Zod schema for input validation
`normalizeParams(params, context, client)`	async	Stage 2 — resolve defaults, validate format
`coreAction(normalised, context, client)`	async	Stage 4 — build the transaction or perform the query
`secondaryAction(request, client, context)`	async	Stage 6 — sign/submit the transaction (no-op for queries)

Optional overrides:

outputParser

shouldSecondaryAction

(return

false

for query-only tools),

handleError

, and the four hook methods.

Tool Types

Mutation tools — state-changing operations (token create/mint/transfer, account update, topic submit).

coreAction

builds the

Transaction

secondaryAction

calls

handleTransaction()

. Use

transactionToolOutputParser

Query tools — read-only operations (token info, balances, mirror-node fetches).

coreAction

returns the result directly. Override

shouldSecondaryAction

to return

false

. Use

untypedQueryOutputParser

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

typescript

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

typescript

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

Step 3: Define Parameters with Zod

typescript

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'),
  });
};

type MyToolParams = z.infer<ReturnType<typeof myToolParameters>>;

See

references/zod-schema-patterns.md

for common Hedera parameter patterns.

Step 4: Implement the BaseTool subclass (mutation example)

typescript

import { Client, Status } from '@hiero-ledger/sdk';
import {
  BaseTool,
  Context,
  handleTransaction,
  RawTransactionResponse,
  transactionToolOutputParser,
} from '@hashgraph/hedera-agent-kit';

const postProcess = (response: RawTransactionResponse) =>
  `Operation completed.
Transaction ID: ${response.transactionId}`;

export class MyTool extends BaseTool<MyToolParams, MyToolParams> {
  method = MY_TOOL_NAME;
  name = 'My Tool Display Name';
  description: string;
  parameters: ReturnType<typeof myToolParameters>;
  outputParser = transactionToolOutputParser;

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

  // Stage 2 — resolve defaults
  async normalizeParams(params: MyToolParams) {
    return params;
  }

  // Stage 4 — build the transaction (do not sign here)
  async coreAction(params: MyToolParams, _context: Context, _client: Client) {
    // return new SomeTransaction()...;
    return undefined as any;
  }

  // Stage 6 — sign and submit
  async secondaryAction(transaction: any, client: Client, context: Context) {
    return handleTransaction(transaction, client, context, postProcess);
  }

  async handleError(error: unknown) {
    const message = 'Failed to execute' + (error instanceof Error ? `: ${error.message}` : '');
    console.error(`[${MY_TOOL_NAME}]`, message);
    return { raw: { status: Status.InvalidTransaction, error: message }, humanMessage: message };
  }
}

Step 5: Export a Factory

typescript

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

The factory pattern lets the plugin's

tools(context)

function instantiate a fresh tool per request with the right context bound.

Query-tool variant — skip stage 6

For read-only tools, override

shouldSecondaryAction

so the lifecycle stops after

coreAction

, and have

secondaryAction

pass the result through unchanged:

typescript

export class MyQueryTool extends BaseTool<MyToolParams, MyToolParams> {
  // ... method/name/description/parameters as above ...
  outputParser = untypedQueryOutputParser;

  async normalizeParams(params: MyToolParams) {
    return params;
  }

  async coreAction(params: MyToolParams, _context: Context, client: Client) {
    return await someHederaQuery(params, client);
  }

  async shouldSecondaryAction() {
    return false;
  }

  async secondaryAction(result: any) {
    return result;
  }
}

Creating the Plugin Index

typescript

import { Context, Plugin } from '@hashgraph/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

secondaryAction

typically delegates to

handleTransaction

, which calls a

postProcess

function with the raw transaction response:

typescript

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

RETURN_BYTES

mode —

raw.bytes

is a

Uint8Array

When a tool runs in

RETURN_BYTES

mode,

raw.bytes

returned by

ResponseParserService

is always a plain

Uint8Array

in both Node.js and browser environments. Pass it directly to

Transaction.fromBytes()

— no manual conversion is needed.

typescript

const bytes = toolCall.parsedData.raw.bytes;
const tx = Transaction.fromBytes(bytes);

Naming Conventions

Element	Convention	Example
Plugin name	kebab-case	`my-token-plugin`
Plugin variable	camelCase	`myTokenPlugin`
Tool class	PascalCase + `Tool`	`CreateTokenTool`
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

typescript

// From @hashgraph/hedera-agent-kit (core)
import {
  Context,
  Plugin,
  BaseTool,
  handleTransaction,
  RawTransactionResponse,
  transactionToolOutputParser,
  untypedQueryOutputParser,
} from '@hashgraph/hedera-agent-kit';

// Built-in plugins live in the /plugins subpath
import { coreTokenPlugin, coreAccountPlugin } from '@hashgraph/hedera-agent-kit/plugins';

// Hedera SDK is a peer dependency
import { Client, Status } from '@hiero-ledger/sdk';

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

Additional Resources

Reference Files

For detailed patterns and techniques, consult:

references/plugin-interface.md
- Plugin interface,
```
BaseTool
```
lifecycle in depth
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/
- Minimal
```
BaseTool
```
query (starter template)

examples/token-plugin/
- Mutation (

CreateTokenTool

) and query (

GetTokenInfoTool

)

BaseTool

subclasses

Best Practices

One file per tool, named after the tool in kebab-case
Group related tools under category directories in
```
tools/
```
Stable class names:
```
<DoesWhat>Tool
```
(e.g.,
```
CreateTokenTool
```
)
Resolve defaults in
normalizeParams
, not in
```
coreAction
```
— keeps the build step pure
Build, don't submit, in
coreAction
— submission belongs in
```
secondaryAction
```
where hooks can react
Override
handleError
so logs are tagged with the tool method
Validate with Zod's
.describe()
— every field; descriptions guide the agent
Export tool name constants so consumers can reference tools programmatically

Registering a Plugin with a Toolkit

Plugins are passed explicitly to the toolkit you choose. Toolkits live in dedicated packages — pick the one that matches your framework:

Framework	Toolkit package
LangChain	`@hashgraph/hedera-agent-kit-langchain`
Vercel AI SDK	`@hashgraph/hedera-agent-kit-ai-sdk`
ElizaOS	`@hashgraph/hedera-agent-kit-elizaos`
MCP	`@hashgraph/hedera-agent-kit-mcp`

Empty
plugins
array means zero tools. List every plugin you need explicitly, or use
allCorePlugins
from the
/plugins
subpath to load every built-in core plugin at once.

typescript

import { Client, PrivateKey } from '@hiero-ledger/sdk';
import { AgentMode } from '@hashgraph/hedera-agent-kit';
import { coreTokenPlugin, coreAccountPlugin } from '@hashgraph/hedera-agent-kit/plugins';
import { HederaLangchainToolkit } from '@hashgraph/hedera-agent-kit-langchain';
import { myPlugin } from './my-hedera-plugin';

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

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

const tools = toolkit.getTools();

To load every built-in core plugin at once, import

allCorePlugins

typescript

import { allCorePlugins } from '@hashgraph/hedera-agent-kit/plugins';
// ...
plugins: [...allCorePlugins, myPlugin],

Workflow Summary

Create plugin directory with
```
index.ts
```
and
```
tools/
```
subdirectory
For each tool, write a
```
BaseTool
```
subclass and a factory function in its own file
Export tools from
```
index.ts
```
along with tool name constants
Pass the plugin in the toolkit's
```
configuration.plugins
```
array
Tools become available to the AI agent

For complete working examples, see the

examples/

directory.

agent-kit-plugin

NPX Install

Tags

SKILL.md Content

Creating Hedera Agent Kit Plugins

Quick Start

Plugin Interface

`BaseTool`

Tool Types

File Structure Pattern

Creating a Tool

Step 1: Define the Tool Constant

Step 2: Create the Prompt Function

Step 3: Define Parameters with Zod

Step 4: Implement the BaseTool subclass (mutation example)

Step 5: Export a Factory

Query-tool variant — skip stage 6

Creating the Plugin Index

Post-Processing Results

`RETURN_BYTES`
mode —
`raw.bytes`
is a
`Uint8Array`

Naming Conventions

Common Imports

Additional Resources

Reference Files

Example Files

Best Practices

Registering a Plugin with a Toolkit

Workflow Summary