Skip to main content

Hashgraph Online Conversational Agent

The Conversational Agent (@hashgraphonline/conversational-agent) is a comprehensive AI agent that implements Hashgraph Consensus Standards (HCS) for agent communication, registry management, and content inscription on the Hedera Hashgraph.

Conversational Agent CLI

Overview​

This package provides a standalone conversational AI agent built on top of hedera-agent-kit v2.0.3, providing access to all Hedera Hashgraph functionality while adding:

  • 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
  • CLI: Beautiful terminal interface for interactive agent communication
  • Core Hedera Tools: Complete access to account, token, file, consensus, and smart contract services

Installation​

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

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

Choosing Models & Providers​

The agent can run against multiple LLM providers. Configure the provider and model with llmProvider and openAIModelName (the name is historical; it carries the model string for any provider).

Supported values for llmProvider:

  • openai: uses OpenAI models (e.g., gpt-4o, gpt-4o-mini).
  • anthropic: uses Claude models (e.g., claude-3-7-sonnet-latest).
  • openrouter: uses OpenRouter routing (prefer vendor-prefixed models like openai/gpt-4o-mini).

Defaults from the SDK:

  • llmProvider: openai
  • openAIModelName: gpt-4o
  • network: testnet

OpenAI example​

const agent = new ConversationalAgent({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  llmProvider: 'openai',
  openAIApiKey: process.env.OPENAI_API_KEY!,
  openAIModelName: process.env.OPENAI_MODEL || 'gpt-4o-mini',
});
await agent.initialize();

Anthropic example​

const agent = new ConversationalAgent({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  llmProvider: 'anthropic',
  openAIApiKey: process.env.ANTHROPIC_API_KEY!,
  openAIModelName: process.env.ANTHROPIC_MODEL || 'claude-3-7-sonnet-latest',
});
await agent.initialize();

OpenRouter example​

const agent = new ConversationalAgent({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  llmProvider: 'openrouter',
  // Accepts either OPENROUTER_API_KEY or OPENAI_KEY (sk-or-...)
  openAIApiKey: process.env.OPENROUTER_API_KEY!,
  openRouterApiKey: process.env.OPENROUTER_API_KEY!,
  openRouterBaseURL:
    process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api/v1',
  // Prefer vendor-prefixed model ids (e.g., 'openai/gpt-4o-mini'). 'openrouter/auto' may require candidates.
  openAIModelName: process.env.OPENROUTER_MODEL || 'openai/gpt-4o-mini',
});
await agent.initialize();

Tips for OpenRouter routing:

  • When using openrouter/auto, some endpoints require a list of candidate models. If you encounter “No models provided”, set OPENROUTER_MODEL to a specific model (e.g., openai/gpt-4o-mini) or consult OpenRouter routing docs to pass candidates in your integration tests.
  • Ensure you send a valid Referer/Title in dashboards; this package does so internally.

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"'
);

// Transfer HBAR
const transferResponse = await agent.processMessage(
  'I want to send 1 HBAR to 0.0.800'
);

console.log(response.response);

// Or use returnBytes mode for external signing
const bytesAgent = new ConversationalAgent({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  openAIApiKey: process.env.OPENAI_API_KEY!,
  operationalMode: 'returnBytes',
  userAccountId: '0.0.12345',
});

await bytesAgent.initialize();

const bytesResponse = await bytesAgent.processMessage(
  'Transfer 5 HBAR to 0.0.98765'
);

if (bytesResponse.transactionBytes) {
  console.log('Transaction bytes:', bytesResponse.transactionBytes);
}

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
  • MCP Support: Extend agent capabilities with Model Context Protocol servers for file operations, databases, and external services

How It Works​

Command Line Interface (CLI)​

The package includes a beautiful terminal interface built with Ink:

# 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 HCS improvement proposals design patterns
  • 💬 Interactive Chat - Chat with your Hashgraph Online agent
  • 🔐 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

Available Tools​

The Conversational Agent leverages hedera-agent-kit v2.0.3 internally, providing comprehensive access to Hedera Hashgraph 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 (11 tools)​

  • Agent Management: RegisterAgentTool, FindRegistrationsTool, RetrieveProfileTool
  • Connection Management: InitiateConnectionTool, ListConnectionsTool, ConnectionMonitorTool, ManageConnectionRequestsTool, AcceptConnectionRequestTool, ListUnapprovedConnectionRequestsTool
  • Messaging: SendMessageToConnectionTool, CheckMessagesTool

HCS-2 Registry Management (6 tools)​

  • Registry Operations: CreateRegistryTool, RegisterEntryTool, UpdateEntryTool, DeleteEntryTool, MigrateRegistryTool, QueryRegistryTool

Inscription Tools (5 tools)​

  • Content Inscription: InscribeFromUrlTool, InscribeFromFileTool, InscribeFromBufferTool, InscribeHashinalTool, RetrieveInscriptionTool

Natural Language Commands​

// Agent registration
'Register me as an AI assistant named HelperBot with ai and assistant tags';

// Registry management
'Create a new HCS-2 topic registry';
'Register topic 0.0.98765 in registry 0.0.123456';

// Content inscription
'Inscribe the content from https://example.com/data.json';
"Create a Hashinal NFT with name 'My NFT' and description 'Test NFT'";

// Finding agents
'Find all agents with ai tag';
'Search for agents with data processing capability';

// Connections
'Connect to agent 0.0.123456';
'List my active connections';
'Accept connection request 1';

// Messaging
"Send 'Hello' to connection 1";
'Check messages from agent 0.0.98765';

Creating Custom Plugins​

Extend the agent with custom plugins:

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

Using Custom Plugins​

const agent = new ConversationalAgent({
  // ... configuration
  additionalPlugins: [new MyCustomPlugin()],
});

View the complete Plugin Development Guide →

Using returnBytes Mode​

The agent can be configured to return transaction bytes instead of executing them directly. This is useful when you want to review or sign transactions externally:

import { ConversationalAgent } from '@hashgraphonline/conversational-agent';
import { Client, Transaction, PrivateKey } from '@hashgraph/sdk';

const agent = new ConversationalAgent({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  network: 'testnet',
  openAIApiKey: process.env.OPENAI_API_KEY!,
  operationalMode: 'returnBytes', // Return transaction bytes instead of executing
  userAccountId: '0.0.12345', // The account that will sign the transaction
  // Optionally, provide a wallet executor to submit bytes and return a tx id
  walletExecutor: async (base64, network) => {
    // Submit to a connected wallet here and return its transaction id
    return { transactionId: '[email protected]' };
  },
});

await agent.initialize();

// The agent will return transaction bytes for operations
const response = await agent.processMessage('Transfer 5 HBAR to 0.0.98765');

if (response.transactionBytes) {
  // Decode the transaction bytes
  const transaction = Transaction.fromBytes(
    Buffer.from(response.transactionBytes, 'base64')
  );

  // Sign the transaction with your private key
  const privateKey = PrivateKey.fromString(process.env.USER_PRIVATE_KEY!);
  const signedTransaction = transaction.sign(privateKey);

  // Submit to the Hedera Hashgraph
  const client = Client.forTestnet();
  client.setOperator('0.0.12345', privateKey);

  const txResponse = await signedTransaction.execute(client);
  const receipt = await txResponse.getReceipt(client);

  console.log('Transaction status:', receipt.status.toString());
  console.log('Transaction ID:', txResponse.transactionId.toString());
}

When using returnBytes mode:

  • The agent prepares transactions but doesn't execute them
  • Transaction bytes are returned as base64-encoded strings
  • You can decode, sign, and submit the transaction using the Hedera SDK
  • This mode is ideal for wallet integrations, multi-signature scenarios, and when you need transaction review before execution

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

MCP (Model Context Protocol) Integration​

The Conversational Agent supports MCP servers, enabling integration with external tools and services. This allows your agent to access file systems, databases, and third-party APIs.

Quick MCP Setup​

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

// Create an agent with MCP servers
const agent = ConversationalAgent.withMCP(
  {
    accountId: '0.0.123456',
    privateKey: 'your-private-key',
    openAIApiKey: 'your-openai-key',
  },
  [
    MCPServers.filesystem('/home/user/documents'),
    MCPServers.github('your-github-token'),
  ]
);

await agent.initialize();

// Agent can now access files and GitHub
const response = await agent.processMessage(
  'Read the README.md file and create a GitHub issue about any TODOs'
);

Available MCP Servers​

  • filesystem: Read, write, and manage local files
  • github: Create issues, manage repositories
  • slack: Send messages to Slack channels
  • postgres/sqlite: Query and manage databases
  • googleDrive: Access Google Drive documents

Learn more about MCP Integration →

Configuration Options​

OptionTypeDefaultDescription
accountIdstringrequiredHedera account ID
privateKeystringrequired in autonomousPrivate key (omit in returnBytes mode)
network'mainnet' | 'testnet' | 'previewnet''testnet'Hedera network
openAIApiKeystringrequiredAPI key for selected provider
openAIModelNamestring'gpt-4o'Model id for the LLM
llmProvider'openai' | 'anthropic' | 'openrouter''openai'LLM provider
verbosebooleanfalseVerbose debug logging
operationalMode'autonomous' | 'returnBytes''autonomous'Execution mode
userAccountIdstringundefinedEnd-user account when scheduling/user context
additionalPluginsBasePlugin[][]Extra plugins to load
enabledPluginsstring[]undefinedOnly enable plugins matching these IDs
toolFilter(tool: Tool) => booleanundefinedPredicate to include/exclude tools
stateManagerIStateManagerOpenConvaiStateCustom state manager
mirrorNodeConfigobjectundefinedMirror node configuration
disableLoggingbooleanfalseSilence logs (errors still emitted)
scheduleUserTransactionsInBytesModebooleanundefinedSchedule transactions in bytes mode
entityMemoryEnabledbooleantrueEnable LLM-based entity memory
entityMemoryConfigSmartMemoryConfigundefinedEntity memory window/config
entityMemoryProvider'openai' | 'anthropic' | 'openrouter'inherits llmProviderProvider for entity extraction
entityMemoryModelNamestringper-providerModel for entity extraction
openRouterApiKeystringundefinedAPI key for OpenRouter
openRouterBaseURLstring'https://openrouter.ai/api/v1'Override OpenRouter base URL
mcpServersMCPServerConfig[]undefinedMCP servers to connect to
walletExecutor(base64, network) => Promise<string>undefinedWallet callback used in returnBytes mode
customSignerFactory(args) => AbstractSignerundefinedOverride signer selection

Entity Memory​

  • Enable entity extraction and association tracking across conversations by setting entityMemoryEnabled: true (default is true).
  • Configure limits via entityMemoryConfig:
    • maxTokens: token cap for active memory window
    • reserveTokens: tokens reserved for response generation
    • modelName: LLM used for token counting
    • storageLimit: max messages to persist in content storage

Example:

const agent = new ConversationalAgent({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  privateKey: process.env.HEDERA_PRIVATE_KEY!,
  openAIApiKey: process.env.OPENAI_API_KEY!,
  entityMemoryEnabled: true,
  entityMemoryConfig: {
    maxTokens: 6000,
    reserveTokens: 1000,
    storageLimit: 500,
  },
});

LLM Provider​

  • Select provider with llmProvider: 'openai' | 'anthropic' (default: openai).
  • Use openAIModelName to select model for the chosen provider.
    • OpenAI example: gpt-4o
    • Anthropic example: claude-3-7-sonnet-latest

MCP Tooling Context​

  • Each MCPServerConfig supports optional fields:
    • additionalContext: guidance to tell the agent when to use the server
    • toolDescriptions: map of toolName -> description to override/enhance defaults

See MCP Servers for full examples.

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.

Documentation​

Resources​