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:0.0.1234@0.0.5678"

// 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);

MCP Server Examples​

File Management Agent​

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

async function fileManagementExample() {
  // Create agent with filesystem access
  const agent = ConversationalAgent.withMCP(
    {
      accountId: process.env.HEDERA_ACCOUNT_ID!,
      privateKey: process.env.HEDERA_PRIVATE_KEY!,
      openAIApiKey: process.env.OPENAI_API_KEY!,
    },
    [MCPServers.filesystem('/home/user/projects')]
  );

  await agent.initialize();

  console.log('\n=== File Operations ===');
  
  // Read and analyze files
  await agent.processMessage(
    "Read all JavaScript files in the src directory and list the exported functions"
  );

  // Create documentation
  await agent.processMessage(
    "Create a README.md file with documentation for all the .js files in this directory"
  );

  // Organize files
  await agent.processMessage(
    "Create folders for components, utils, and tests, then move files accordingly"
  );

  // Backup configuration
  await agent.processMessage(
    "Create a backup of all .json configuration files in a backup folder with today's date"
  );
}

fileManagementExample().catch(console.error);

Development Assistant​

async function developmentAssistant() {
  // Agent with multiple MCP servers
  const agent = new ConversationalAgent({
    accountId: process.env.HEDERA_ACCOUNT_ID!,
    privateKey: process.env.HEDERA_PRIVATE_KEY!,
    openAIApiKey: process.env.OPENAI_API_KEY!,
    mcpServers: [
      MCPServers.filesystem('./'),
      MCPServers.github(process.env.GITHUB_TOKEN!),
      MCPServers.postgres('postgresql://localhost/devdb')
    ]
  });

  await agent.initialize();

  // Complete development workflow
  console.log('\n=== Development Workflow ===');
  
  // Analyze codebase
  await agent.processMessage(
    "Read all test files and identify which components lack test coverage"
  );

  // Create GitHub issues
  await agent.processMessage(
    "Create GitHub issues for each component that needs tests"
  );

  // Update database
  await agent.processMessage(
    "Update the code_quality table with the current test coverage metrics"
  );

  // Generate report
  await agent.processMessage(
    "Create a markdown report summarizing code quality and save it as quality-report.md"
  );
}

Data Analysis Agent​

async function dataAnalysisExample() {
  const agent = ConversationalAgent.withMCP(
    {
      accountId: process.env.HEDERA_ACCOUNT_ID!,
      privateKey: process.env.HEDERA_PRIVATE_KEY!,
      openAIApiKey: process.env.OPENAI_API_KEY!,
    },
    [
      MCPServers.postgres('postgresql://localhost/analytics'),
      MCPServers.filesystem('./reports')
    ]
  );

  await agent.initialize();

  console.log('\n=== Data Analysis ===');
  
  // Query and analyze data
  await agent.processMessage(
    "Query the sales table for Q4 data and calculate the growth rate compared to Q3"
  );

  // Generate visualizations data
  await agent.processMessage(
    "Create a JSON file with monthly sales data formatted for chart visualization"
  );

  // Create comprehensive report
  await agent.processMessage(
    "Write a detailed analysis report including trends, insights, and recommendations, save as q4-analysis.md"
  );
}

Agent with Filtered MCP Tools​

async function filteredMCPExample() {
  // Agent with tool filtering for safety
  const agent = new ConversationalAgent({
    accountId: process.env.HEDERA_ACCOUNT_ID!,
    privateKey: process.env.HEDERA_PRIVATE_KEY!,
    openAIApiKey: process.env.OPENAI_API_KEY!,
    mcpServers: [MCPServers.filesystem('/tmp/safe-directory')],
    toolFilter: (tool) => {
      // Only allow read operations and safe writes
      const safeTool = ['read_file', 'list_directory', 'write_file'].includes(tool.name);
      const unsafeOperation = tool.name.includes('delete') || tool.name.includes('remove');
      return safeTool && !unsafeOperation;
    }
  });

  await agent.initialize();

  // These operations will work
  await agent.processMessage("Read all text files");
  await agent.processMessage("Create a summary.txt file");

  // These will be blocked by the filter
  await agent.processMessage("Delete old files"); // Blocked
  await agent.processMessage("Remove temporary directory"); // Blocked
}

Combined HCS and MCP Operations​

async function combinedOperations() {
  // Agent with HCS tools and MCP servers
  const agent = new ConversationalAgent({
    accountId: process.env.HEDERA_ACCOUNT_ID!,
    privateKey: process.env.HEDERA_PRIVATE_KEY!,
    openAIApiKey: process.env.OPENAI_API_KEY!,
    mcpServers: [
      MCPServers.filesystem('./agent-data'),
      MCPServers.postgres('postgresql://localhost/agentdb')
    ]
  });

  await agent.initialize();

  console.log('\n=== Combined Operations ===');
  
  // Register agent and save profile
  await agent.processMessage(
    "Register me as DataAnalyzer with analytics capabilities"
  );

  await agent.processMessage(
    "Save my agent profile to agent-profile.json"
  );

  // Find agents and save results
  await agent.processMessage(
    "Find all agents with analytics tag and save the list to analytics-agents.json"
  );

  // Track connections in database
  await agent.processMessage(
    "Connect to agent 0.0.123456"
  );

  await agent.processMessage(
    "Insert this connection into the agent_connections table"
  );

  // Inscribe important data
  await agent.processMessage(
    "Read agent-profile.json and inscribe it on Hedera"
  );
}

See Also​