JSPM

  • Created
  • Published
  • Downloads 100
  • Score
    100M100P100Q87189F
  • License Apache-2.0

Hashgraph Online conversational AI agent implementing HCS-10 communication, HCS-2 registries, and content inscription on Hedera

Package Exports

  • @hashgraphonline/conversational-agent
  • @hashgraphonline/conversational-agent/package.json

Readme

Hashgraph Online Conversational Agent

A conversational AI agent that implements Hashgraph Consensus Standards (HCS) for agent communication, registry management, and content inscription on the Hedera network.

This package is built and maintained by Hashgraph Online, a consortium of leading Hashgraph organizations within the Hedera ecosystem.

📚 Conversational Agent Documentation
📖 HCS Standards Documentation

Overview

The Hashgraph Online Conversational Agent provides a comprehensive AI agent implementation that supports:

  • HCS-10: AI Agent Communication standard for trustless peer-to-peer messaging
  • HCS-2: Registry management for decentralized data storage
  • Inscription: Content inscription following Hashgraph Consensus Standards

Important Compatibility Note

This package is designed to work as a standalone conversational agent. While it can be used with hedera-agent-kit version 2.0.3 only (version 3.x no longer supports the plugin architecture), the recommended approach is to use the ConversationalAgent class directly.

Installation

# Install the conversational agent
npm install @hashgraphonline/conversational-agent

# Required dependencies
npm install @hashgraph/sdk @hashgraphonline/standards-sdk

Quick Start

import { ConversationalAgent } from '@hashgraphonline/conversational-agent';

// Initialize the agent
const agent = new ConversationalAgent({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  openAIApiKey: process.env.OPENAI_API_KEY!,
  openAIModelName: 'gpt-4o',
  verbose: true
});

// Initialize (automatically detects key type)
await agent.initialize();

// Process a message
const response = await agent.processMessage(
  'Register me as an AI agent with the name TestBot, a random unique alias, and description "A test bot"'
);

console.log(response.response);

Features

  • Automatic Key Detection: Smart detection of ED25519 and ECDSA key types via mirror node
  • Multiple HCS Standards: Built-in support for HCS-10, HCS-2, and inscription standards
  • Three Plugin System: HCS10Plugin, HCS2Plugin, and InscribePlugin
  • TypeScript Support: Full type definitions for all components
  • State Management: Integrated state management for agent operations
  • CLI Interface: Beautiful terminal interface for interactive agent communication

Available Tools

The Conversational Agent includes all tools from the @hashgraphonline/hedera-agent-kit package, providing comprehensive access to Hedera network functionality:

Core Hedera Tools (from hedera-agent-kit)

  • Account Management: Create accounts, transfer HBAR, manage allowances, get account info
  • Token Service (HTS): Create tokens/NFTs, mint, burn, transfer, manage token properties
  • Smart Contract Service: Deploy contracts, execute functions, query contract state
  • File Service: Create, append, update, delete files on Hedera
  • Consensus Service: Create topics, submit messages, retrieve topic info
  • Network Queries: Get network info, HBAR price, transaction details

HCS-10 Agent Communication Tools

  • RegisterAgentTool: Register new agents with capabilities and tags
  • FindRegistrationsTool: Search for agents by account ID or tags
  • RetrieveProfileTool: Get detailed agent profiles
  • InitiateConnectionTool: Start connections with other agents
  • ListConnectionsTool: View active connections
  • ConnectionMonitorTool: Monitor for incoming connection requests
  • ManageConnectionRequestsTool: Handle pending connections
  • AcceptConnectionRequestTool: Accept incoming connections
  • ListUnapprovedConnectionRequestsTool: View pending requests
  • SendMessageToConnectionTool: Send messages to connected agents
  • CheckMessagesTool: Retrieve messages from connections

HCS-2 Registry Tools

  • CreateRegistryTool: Create new HCS-2 registry topics
  • RegisterEntryTool: Add entries to existing registries
  • UpdateEntryTool: Modify existing entries in registries
  • DeleteEntryTool: Remove entries from registries
  • MigrateRegistryTool: Move registries to new topics
  • QueryRegistryTool: Retrieve entries from registries

Inscription Tools

  • InscribeFromUrlTool: Inscribe content from URLs
  • InscribeFromFileTool: Inscribe content from local files
  • InscribeFromBufferTool: Inscribe content from memory buffers
  • InscribeHashinalTool: Create Hashinal NFTs with specific attributes
  • RetrieveInscriptionTool: Get details of existing inscriptions

Command Line Interface (CLI)

This package includes a beautiful terminal interface built with Ink that follows Hashgraph Consensus Standards design patterns.

# Run the interactive CLI
pnpm cli

# Or with environment variables
export HEDERA_ACCOUNT_ID=0.0.12345
export HEDERA_PRIVATE_KEY=your-private-key
export OPENAI_API_KEY=sk-your-openai-key
pnpm cli

# Or with command line arguments
pnpm cli -- --account-id=0.0.12345 --private-key=... --openai-api-key=sk-...

CLI Features

  • 🎨 Beautiful Terminal UI - Styled with Hashgraph Consensus Standards improvement proposals design patterns
  • 💬 Interactive Chat - Chat with your Hashgraph Online agent in a clean terminal interface
  • 🔐 Secure Configuration - Masked input for sensitive credentials
  • 🌈 Gradient Text & Colors - Brand-consistent color scheme
  • 🚀 Fast & Responsive - Built with React for smooth interactions
  • 📊 Transaction Details - See transaction IDs and network responses

Creating Custom Plugins

You can extend the conversational agent with custom plugins. Here's how to create one:

Plugin Structure

See our comprehensive Plugin Development Guide for detailed instructions.

import {
  GenericPluginContext,
  HederaTool,
  BasePlugin,
  HederaAgentKit,
} from 'hedera-agent-kit';

export class MyCustomPlugin extends BasePlugin {
  id = 'my-plugin';
  name = 'MyCustomPlugin';
  description = 'A custom plugin for specific functionality';
  version = '1.0.0';
  author = 'Your Name';
  namespace = 'myplugin';

  private tools: HederaTool[] = [];

  override async initialize(context: GenericPluginContext): Promise<void> {
    await super.initialize(context);
    // Initialize your plugin and tools
  }

  getTools(): HederaTool[] {
    return this.tools;
  }
}

Creating a Custom Tool

Tools extend either BaseHederaTransactionTool or BaseHederaQueryTool:

import { z } from 'zod';
import {
  BaseHederaTransactionTool,
  BaseHederaTransactionToolParams,
  BaseServiceBuilder,
} from 'hedera-agent-kit';

const MyToolSchema = z.object({
  param1: z.string().describe('First parameter'),
  param2: z.number().optional().describe('Optional second parameter'),
});

export class MyCustomTool extends BaseHederaTransactionTool<typeof MyToolSchema> {
  name = 'my-custom-tool';
  description = 'Performs a custom Hedera transaction';
  specificInputSchema = MyToolSchema;
  namespace = 'custom';

  constructor(params: BaseHederaTransactionToolParams) {
    super(params);
  }

  protected getServiceBuilder(): BaseServiceBuilder {
    return this.hederaKit.consensus(); // or hts(), account(), etc.
  }

  protected async callBuilderMethod(
    builder: BaseServiceBuilder,
    specificArgs: z.infer<typeof MyToolSchema>
  ): Promise<void> {
    // Implement your transaction logic
  }
}

Using Custom Plugins

import { ConversationalAgent } from '@hashgraphonline/conversational-agent';
import { MyCustomPlugin } from './plugins/MyCustomPlugin';

const agent = new ConversationalAgent({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  openAIApiKey: process.env.OPENAI_API_KEY!,
  // Add your custom plugins
  additionalPlugins: [new MyCustomPlugin()]
});

await agent.initialize();

// Your custom tools are now available to the agent
const response = await agent.processMessage('Use my custom tool with param1 "test"');

Plugin Best Practices

  1. Extend Correct Base Classes: Use BaseHederaTransactionTool or BaseHederaQueryTool for tools
  2. Define Clear Schemas: Use Zod schemas to clearly define tool inputs
  3. Error Handling: Always handle errors gracefully and return meaningful messages
  4. State Management: If your plugin needs state, consider implementing a custom state manager
  5. Documentation: Provide clear descriptions for your plugin and tools

For more details, see our Plugin Development Guide.

Configuration Options

Option Type Default Description
accountId string required Hedera account ID (e.g., '0.0.12345')
privateKey string required Private key for the account
network NetworkType 'testnet' Network to connect to ('mainnet' or 'testnet')
openAIApiKey string required OpenAI API key for the LLM
openAIModelName string 'gpt-4o' OpenAI model to use
verbose boolean false Enable verbose logging
operationalMode AgentOperationalMode 'autonomous' 'autonomous' or 'returnBytes'
userAccountId string undefined User's account ID for transaction context
customSystemMessagePreamble string instructions Custom system message prefix
customSystemMessagePostamble string undefined Custom system message suffix
additionalPlugins BasePlugin[] [] Additional plugins to load
stateManager IStateManager OpenConvaiState Custom state manager
scheduleUserTransactionsInBytesMode boolean false Schedule transactions in bytes mode
mirrorNodeConfig MirrorNodeConfig undefined Custom mirror node configuration
disableLogging boolean false Disable all logging
enabledPlugins string[] undefined Filter which plugins to enable by ID

Environment Variables

# Required
HEDERA_ACCOUNT_ID=0.0.12345
HEDERA_PRIVATE_KEY=your_private_key_here
OPENAI_API_KEY=your_openai_api_key

# Optional
HEDERA_NETWORK=testnet  # defaults to testnet

Advanced Usage

Direct Plugin Access

const agent = new ConversationalAgent({ /* config */ });
await agent.initialize();

// Access plugins directly
const hcs10Plugin = agent.hcs10Plugin;
const hcs2Plugin = agent.hcs2Plugin;
const inscribePlugin = agent.inscribePlugin;

// Access the underlying Hedera agent
const hederaAgent = agent.getConversationalAgent();

// Access state manager
const stateManager = agent.getStateManager();

Custom State Management

import { OpenConvaiState } from '@hashgraphonline/standards-agent-kit';

// Create custom state manager
const customStateManager = new OpenConvaiState();

const agent = new ConversationalAgent({
  // ... other config
  stateManager: customStateManager
});

Using Plugin Presets

The ConversationalAgent provides static helper functions to create agents with specific plugin configurations:

// Create agent with only HTS (Hedera Token Service) tools
const htsAgent = ConversationalAgent.withHTS({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  openAIApiKey: process.env.OPENAI_API_KEY!
});

// Create agent with only HCS-2 registry tools
const hcs2Agent = ConversationalAgent.withHCS2({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  openAIApiKey: process.env.OPENAI_API_KEY!
});

// Other presets available:
// ConversationalAgent.withHCS10() - Only HCS-10 agent communication tools
// ConversationalAgent.withInscribe() - Only inscription tools
// ConversationalAgent.withAccount() - Only account management tools
// ConversationalAgent.withFileService() - Only file service tools
// ConversationalAgent.withConsensusService() - Only consensus service tools
// ConversationalAgent.withSmartContract() - Only smart contract tools
// ConversationalAgent.withAllStandards() - All HCS standards plugins (HCS-10, HCS-2, Inscribe)
// ConversationalAgent.minimal() - Only basic account tools

Plugin Filtering

You can also manually specify which plugins to enable using the enabledPlugins option:

const agent = new ConversationalAgent({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  openAIApiKey: process.env.OPENAI_API_KEY!,
  // Only enable specific plugins by their ID
  enabledPlugins: ['hcs-10', 'hts-token', 'account']
});

Available plugin IDs:

  • Standard plugins: hcs-10, hcs-2, inscribe
  • Core Hedera plugins: hts-token, account, file-service, consensus-service, smart-contract, network

Legacy Plugin Usage (hedera-agent-kit 2.0.3 only)

If you need to use this with hedera-agent-kit 2.0.3:

import { HederaConversationalAgent, ServerSigner } from 'hedera-agent-kit';
import { HCS10Plugin, HCS2Plugin, InscribePlugin } from '@hashgraphonline/conversational-agent';

const signer = new ServerSigner(accountId, privateKey, network);

const agent = new HederaConversationalAgent(signer, {
  pluginConfig: {
    plugins: [
      new HCS10Plugin(),
      new HCS2Plugin(),
      new InscribePlugin()
    ]
  },
  openAIApiKey: process.env.OPENAI_API_KEY!
});

Resources

License

Apache-2.0