Hedera Plugin Creation

Category: Tools & Productivity | Uploader: hedera-dev | Downloads: 0 | Version: v1.0（Latest）

This skill should be used when the user asks to "create a hedera plugin", "build a hedera agent kit plugin", "extend hedera agent kit", "create custom hedera tools", "add hedera functionality", "write a hedera tool", "implement hedera tool", or needs guidance on Hedera Agent Kit plugin architecture, tool definitions, mutation tools, query tools, or parameter schemas using Zod.

Changelog: Source: GitHub https://github.com/hedera-dev/hedera-skills

Directory Structure

Current level: plugins/agent-kit-plugin/skills/agent-kit-plugin/

📁 examples/
- 📁 simple-plugin/
  - 📁 tools/
    
    📄 greeting.ts 2.8 KB
  - 📄 index.ts 871 B
- 📁 token-plugin/
  - 📁 tools/
    
    📄 create-token.ts 6.0 KB
    
    📄 get-token-info.ts 5.3 KB
  - 📄 index.ts 1.3 KB
📁 references/
- 📄 error-handling.md 10.0 KB
- 📄 plugin-interface.md 5.8 KB
- 📄 prompt-patterns.md 7.8 KB
- 📄 zod-schema-patterns.md 8.5 KB
📄 SKILL.md 8.6 KB

SKILL.md

---
name: Hedera Plugin Creation
description: This skill should be used when the user asks to "create a hedera plugin", "build a hedera agent kit plugin", "extend hedera agent kit", "create custom hedera tools", "add hedera functionality", "write a hedera tool", "implement hedera tool", or needs guidance on Hedera Agent Kit plugin architecture, tool definitions, mutation tools, query tools, or parameter schemas using Zod.
version: 1.0.0
---

# 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`:

```typescript
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:

```typescript
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

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

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

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

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

### Step 4: Implement the Execute Function

```typescript
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

```typescript
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

```typescript
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:

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

```typescript
// 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:

```typescript
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.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

Hedera Plugin Creation

Directory Structure

SKILL.md

Report

Notice