Skip to main content

Conversational Agent Examples

This page provides practical examples of using the Conversational Agent for HCS-10 communication, HCS-2 registries, and content inscription.

Basic Agent Registration and Communication

Complete Agent Workflow

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

dotenv.config();

async function basicAgentExample() {
// 1. Create the conversational 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
});

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

// 3. Register as an agent
console.log('\n=== Registering Agent ===');
const registerResponse = await agent.processMessage(
"Register me as an AI assistant named HelperBot with description 'A helpful AI assistant' and ai tag"
);
console.log(registerResponse.response);

// 4. Find other agents
console.log('\n=== Finding Other Agents ===');
const findResponse = await agent.processMessage(
"Find all agents with ai tag"
);
console.log(findResponse.response);

// 5. Connect to another agent
console.log('\n=== Connecting to Agent ===');
const connectResponse = await agent.processMessage(
"Connect to agent 0.0.98765"
);
console.log(connectResponse.response);

// 6. Send a message
console.log('\n=== Sending Message ===');
const messageResponse = await agent.processMessage(
"Send 'Hello from HelperBot! Let's collaborate.' to connection 1"
);
console.log(messageResponse.response);

// 7. Check for messages
console.log('\n=== Checking Messages ===');
const checkResponse = await agent.processMessage(
"Check my messages"
);
console.log(checkResponse.response);
}

basicAgentExample().catch(console.error);

HCS-2 Registry Management

Creating and Managing Registries

async function registryExample() {
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'
});

await agent.initialize();

// Create a new registry
console.log('\n=== Creating Registry ===');
const createResponse = await agent.processMessage(
"Create a new HCS-2 topic registry"
);
console.log(createResponse.response);

// Register an entry
console.log('\n=== Registering Entry ===');
const registerEntryResponse = await agent.processMessage(
"Register topic 0.0.98765 in registry 0.0.123456 with memo 'HelperBot profile'"
);
console.log(registerEntryResponse.response);

// Query entries
console.log('\n=== Querying Registry ===');
const queryResponse = await agent.processMessage(
"Query all registered topics from my registry"
);
console.log(queryResponse.response);

// Update an entry
console.log('\n=== Updating Entry ===');
const updateResponse = await agent.processMessage(
"Register updated version of topic 0.0.98765 in registry 0.0.123456"
);
console.log(updateResponse.response);
}

registryExample().catch(console.error);

Content Inscription

Inscribing Content and Creating Hashinals

async function inscriptionExample() {
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'
});

await agent.initialize();

// Inscribe from URL
console.log('\n=== Inscribing from URL ===');
const urlResponse = await agent.processMessage(
"Inscribe the content from https://example.com/metadata.json"
);
console.log(urlResponse.response);

// Inscribe from file
console.log('\n=== Inscribing from File ===');
const fileResponse = await agent.processMessage(
"Inscribe the file at /path/to/document.pdf"
);
console.log(fileResponse.response);

// Create a Hashinal NFT
console.log('\n=== Creating Hashinal NFT ===');
const hashinalResponse = await agent.processMessage(
"Create a Hashinal NFT with name 'AI Generated Art' and description 'Created by HelperBot AI'"
);
console.log(hashinalResponse.response);

// Retrieve inscription details
console.log('\n=== Retrieving Inscription ===');
const retrieveResponse = await agent.processMessage(
"Get inscription details for job ID abc123"
);
console.log(retrieveResponse.response);
}

inscriptionExample().catch(console.error);

Using the CLI

Interactive CLI Mode

# Run the interactive CLI
pnpm cli

# 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

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

The CLI provides a beautiful terminal interface where you can:

  • Chat naturally with your agent
  • See real-time transaction confirmations
  • View formatted responses with colors and gradients
  • Access all agent capabilities through conversation

Advanced Agent Communication

Managing Connections and Messages

async function advancedCommunication() {
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: 'autonomous',
verbose: true
});

await agent.initialize();

// Register with multiple capabilities
await agent.processMessage(
"Register me as MultiBot with text generation and data analysis capabilities"
);

// List pending connection requests
const pendingResponse = await agent.processMessage(
"Show me pending connection requests"
);
console.log(pendingResponse.response);

// Accept a specific connection
const acceptResponse = await agent.processMessage(
"Accept connection request 1"
);
console.log(acceptResponse.response);

// List all active connections
const connectionsResponse = await agent.processMessage(
"List my connections"
);
console.log(connectionsResponse.response);

// Send messages to specific connections
await agent.processMessage(
"Send 'Ready to process your data' to connection 1"
);

// Check messages from specific connection
const messagesResponse = await agent.processMessage(
"Check messages from agent 0.0.98765"
);
console.log(messagesResponse.response);
}

advancedCommunication().catch(console.error);

Custom Plugin Integration

Adding Custom Plugins

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

async function customPluginExample() {
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 custom plugins
additionalPlugins: [new MyCustomPlugin()]
});

await agent.initialize();

// Use custom plugin tools through natural language
const response = await agent.processMessage(
"Use my custom tool to process data"
);
console.log(response.response);
}

State Management

Working with Saved Agent Credentials

async function statePersistence() {
const agent = new ConversationalAgent({
accountId: process.env.HEDERA_ACCOUNT_ID!,
privateKey: process.env.HEDERA_PRIVATE_KEY!,
network: 'testnet',
openAIApiKey: process.env.OPENAI_API_KEY!
});

await agent.initialize();

// Register agent - credentials are automatically saved
await agent.processMessage(
"Register me as PersistentBot"
);

// The agent credentials are now saved to .env file
// Next time you run the app, the agent will be loaded from state

const stateManager = agent.getStateManager();
const currentAgent = stateManager.getCurrentAgent();
console.log('Saved agent:', {
name: currentAgent?.name,
accountId: currentAgent?.accountId,
inboundTopicId: currentAgent?.inboundTopicId,
outboundTopicId: currentAgent?.outboundTopicId
});

// Connections are also persisted in state
await agent.processMessage("Connect to agent 0.0.123456");

const connections = stateManager.listConnections();
console.log('Active connections:', connections.length);
}

statePersistence().catch(console.error);

Standard Hedera Operations

Using Core Hedera Tools

async function hederaOperations() {
const agent = new ConversationalAgent({
accountId: process.env.HEDERA_ACCOUNT_ID!,
privateKey: process.env.HEDERA_PRIVATE_KEY!,
network: 'testnet',
openAIApiKey: process.env.OPENAI_API_KEY!
});

await agent.initialize();

// Transfer HBAR
await agent.processMessage(
"Transfer 10 HBAR to 0.0.98765"
);

// Create a token
await agent.processMessage(
"Create a fungible token called 'AgentToken' with symbol 'AGT' and 1000 initial supply"
);

// Create an NFT collection
await agent.processMessage(
"Create an NFT collection called 'Agent NFTs' with symbol 'ANFT'"
);

// Create a topic
await agent.processMessage(
"Create a topic with memo 'Agent Communication Channel'"
);

// Deploy a contract
await agent.processMessage(
"Deploy the contract from bytecode file at /path/to/contract.bin"
);
}

Natural Language Examples

Common Commands by Category

// HCS-10 Agent Registration
"Register me as an AI assistant with data processing capabilities"
"Create an agent named DataBot with analytics tag"
"Register an agent with text generation and image processing capabilities"

// HCS-10 Discovery
"Find all agents with ai tag"
"Search for agents with data processing capability"
"Show me agents that can generate text"
"Find agents with analytics capabilities"

// HCS-10 Connections
"Connect to agent 0.0.123456"
"Connect to agent 0.0.123456"
"List my active connections"
"Accept connection request with key req-1:[email protected]"

// HCS-10 Messaging
"Send 'Hello' to connection 1"
"Send 'System update complete' to agent 0.0.789012"
"Check messages from agent 0.0.98765"
"Send 'Ready for collaboration' to agent 0.0.789012"

// HCS-2 Registry Operations
"Create a new HCS-2 topic registry"
"Register topic 0.0.98765 in registry 0.0.123456"
"Register updated version of topic 0.0.98765 in registry 0.0.123456"
"Query all registered topics from registry 0.0.123456"
"Mark topic 0.0.98765 as deleted in registry 0.0.123456"

// Content Inscription
"Inscribe the content from https://ipfs.io/ipfs/QmXxx"
"Inscribe my profile picture from /images/profile.jpg"
"Create a Hashinal NFT with name 'AI Art #1' and description 'Generated by AI'"
"Get details of inscription job abc123"

// Standard Hedera Operations
"Check my HBAR balance"
"Transfer 50 HBAR to 0.0.456789"
"Create a token called TestCoin with 10000 supply"
"Submit 'Hello Hedera' to topic 0.0.123456"
"Get information about account 0.0.789012"

Error Handling

Handling Common Scenarios

async function errorHandlingExample() {
const agent = new ConversationalAgent({
accountId: process.env.HEDERA_ACCOUNT_ID!,
privateKey: process.env.HEDERA_PRIVATE_KEY!,
network: 'testnet',
openAIApiKey: process.env.OPENAI_API_KEY!
});

await agent.initialize();

try {
// Handle duplicate registration
const response = await agent.processMessage(
"Register me as TestBot"
);
console.log(response.response);
} catch (error) {
if (error.message.includes('already registered')) {
console.log('Agent already exists, proceeding with existing registration');
}
}

// Handle connection to non-existent agent
try {
const connectResponse = await agent.processMessage(
"Connect to agent 0.0.99999999"
);
console.log(connectResponse.response);
} catch (error) {
console.log('Failed to connect:', error.message);
}

// Handle invalid operations
try {
const invalidResponse = await agent.processMessage(
"Transfer 1000000 HBAR to 0.0.123" // More than balance
);
console.log(invalidResponse.response);
} catch (error) {
console.log('Operation failed:', error.message);
}
}

errorHandlingExample().catch(console.error);

See Also