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

!Conversational Agent CLI

Overview

The Hashgraph Online Conversational Agent provides a comprehensive AI agent implementation that supports all tools from the hedera-agent-kit v2 package and the following HCS standards:

- 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

$3

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

``bash


Install the conversational agent

npm install @hashgraphonline/conversational-agent

Required dependencies

npm install @hashgraph/sdk @hashgraphonline/standards-sdk
`

Quick Start

`typescript
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 transfer 1 HBAR to the account 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);
}
`

$3

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. Here's how to execute the transaction after getting the bytes:

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

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 network
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

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
- Core Plugin Suite: HCS10Plugin, HCS2Plugin, InscribePlugin, and HbarPlugin
- 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

Available Tools

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

$3

- 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

$3

- 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

$3

- 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

$3

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

`bash


Run the interactive CLI from the source workspace

pnpm cli

Or invoke the published binary with npx (no local build required)

npx @hashgraphonline/conversational-agent

Provide credentials via environment variables (works for pnpm cli and npx)

export HEDERA_ACCOUNT_ID=0.0.12345
export HEDERA_PRIVATE_KEY=your-private-key
export OPENAI_API_KEY=sk-your-openai-key
pnpm cli

Supply configuration through CLI flags

pnpm cli -- --account-id=0.0.12345 --private-key=... --openai-api-key=sk-...
`

$3

- 🎨 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

$3

Use the same executable to run a single command without the interactive UI. Headless mode activates automatically when you pass a command argument or when the CLI receives non-interactive input.

`bash


Pass the command immediately after the binary

npx @hashgraphonline/conversational-agent "Register me as an AI agent named TestBot"

Or use the explicit flag (useful when the command contains leading dashes)

npx @hashgraphonline/conversational-agent \
--account-id=0.0.12345 \
--private-key=... \
--openai-api-key=sk-... \
--command "Transfer 1 HBAR to 0.0.800"

From the workspace helper script

pnpm cli -- --command "Find my pending connection requests"
`

Headless execution prints structured output prefixed with the speaker (for example [assistant], [error], [transaction]) and returns a non-zero exit code when an error occurs. This makes it suitable for automation, CI tasks, or scripting flows that need machine-readable responses.

Creating Custom Plugins

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

$3

See the Conversational Agent documentation for detailed plugin development guidance.

`typescript
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 {
await super.initialize(context);
// Initialize your plugin and tools
}

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

$3

Tools extend either BaseHederaTransactionTool or BaseHederaQueryTool:

`typescript
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
): Promise {
// Implement your transaction logic
}
}
`

$3

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

$3

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 the Conversational Agent documentation.

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', 'testnet', or 'previewnet') |
| openAIApiKey | string | required | API key used for the default LLM provider and entity memory |
| openAIModelName | string | 'gpt-4o' | Preferred OpenAI model when llmProvider is openai |
| llmProvider | 'openai' \| 'anthropic' \| 'openrouter' | 'openai' | Primary LLM provider for conversational responses |
| verbose | boolean | false | Enable verbose logging |
| operationalMode | AgentOperationalMode | 'autonomous' | 'autonomous' or 'returnBytes' |
| userAccountId | string | undefined | Account ID applied to scheduled transactions in returnBytes mode |
| customSystemMessagePreamble | string | Hashgraph Online system prompt | 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 automatically in returnBytes mode |
| mirrorNodeConfig | MirrorNodeConfig | undefined | Custom mirror node configuration |
| disableLogging | boolean | false | Disable all logging |
| enabledPlugins | string[] | undefined | Filter which plugins to enable by ID |
| toolFilter | (tool: { name: string; namespace?: string }) => boolean | undefined | Predicate to include or exclude tools dynamically |
| mcpServers | MCPServerConfig[] | undefined | Configure MCP servers for Model Context Protocol support |
| walletExecutor | (base64, network) => Promise<{ transactionId: string }> | undefined | Custom executor for wallet-driven transaction submission |
| customSignerFactory | (args) => AbstractSigner | undefined | Override signer selection when initializing the agent |
| entityMemoryEnabled | boolean | true | Enable automatic entity extraction and storage |
| entityMemoryConfig | SmartMemoryConfig | undefined | Custom configuration for entity memory |
| entityMemoryProvider | 'openai' \| 'anthropic' \| 'openrouter' | Matches llmProvider | Provider used for entity extraction and resolution |
| entityMemoryModelName | string | Provider-specific default | Override model used for entity memory operations |
| openRouterApiKey | string | undefined | API key when using OpenRouter (falls back to openAIApiKey) |
| openRouterBaseURL | string | 'https://openrouter.ai/api/v1' | Base URL for OpenRouter requests |

Environment Variables

`bash


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

$3

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

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

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

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

$3

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

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

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

$3

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

`typescript
// 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
// ConversationalAgent.withMCP(options, mcpServers) - Configure Model Context Protocol servers
`

$3

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

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

$3

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

`typescript
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
- MCP Integration Guide
- GitHub Repository

Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, or creating new plugins, your contributions help make the Conversational Agent better for everyone.

$3

If you've created a plugin that extends the Conversational Agent's capabilities, we'd love to include it in the repository. Here's how:

1. Fork the Repository
`bash
git clone https://github.com/hashgraph-online/conversational-agent.git
cd conversational-agent
pnpm install
`

2. Create Your Plugin
- Place your plugin in src/plugins/community/[your-plugin-name]/
- Follow the plugin structure outlined in the Conversational Agent documentation
- Include comprehensive tests in src/plugins/community/[your-plugin-name]/__tests__/
- Add documentation in src/plugins/community/[your-plugin-name]/README.md

3. Plugin Requirements
- Must extend BasePlugin from hedera-agent-kit
- Include clear tool descriptions for AI understanding
- Add proper error handling and validation
- Follow TypeScript best practices
- Include unit tests with >80% coverage
- Document all configuration options
- Add usage examples

4. Submit a Pull Request
- Create a feature branch: git checkout -b feature/add-[plugin-name]-plugin
- Commit your changes with clear messages
- Push to your fork and create a PR
- Include a description of what your plugin does and why it's useful
- Link to any relevant HCS standards or documentation

$3

1. Code Review: Maintainers will review your code for quality, security, and adherence to standards
2. Testing: All tests must pass, and the plugin must work with the latest agent version
3. Documentation: Clear documentation and examples are required
4. Integration: Once approved, your plugin will be added to the community plugins directory

$3

`
src/plugins/community/your-plugin/
├── index.ts # Main plugin export
├── YourPlugin.ts # Plugin implementation
├── tools/ # Tool implementations
│ ├── YourTool1.ts
│ └── YourTool2.ts
├── __tests__/ # Test files
│ ├── YourPlugin.test.ts
│ └── tools/
│ ├── YourTool1.test.ts
│ └── YourTool2.test.ts
├── README.md # Plugin documentation
└── package.json # Plugin metadata (optional)
``

$3

- Code Style: Follow the existing code style and linting rules
- Commits: Use clear, descriptive commit messages
- Documentation: Update relevant documentation for any changes
- Tests: Add tests for new functionality
- Issues: Open an issue before working on major changes

$3

- Join our Telegram community for discussions
- Check existing issues and PRs before starting work
- Ask questions in the #development channel
- Review the HCS Standards for protocol details

License

Apache-2.0