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-sdkQuick 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
- Extend Correct Base Classes: Use
BaseHederaTransactionToolorBaseHederaQueryToolfor tools - Define Clear Schemas: Use Zod schemas to clearly define tool inputs
- Error Handling: Always handle errors gracefully and return meaningful messages
- State Management: If your plugin needs state, consider implementing a custom state manager
- 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 testnetAdvanced 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 toolsPlugin 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
- Conversational Agent Documentation
- Standards Agent Kit Documentation
- HCS Standards Documentation
- GitHub Repository
License
Apache-2.0
