Skip to main content

Getting Started with Conversational Agent

This guide will help you get up and running with the Hashgraph Online Conversational Agent quickly.

Prerequisites​

  • Node.js 18+ and npm/pnpm
  • Hedera testnet account credentials
  • OpenAI API key
  • Optional: Terminal for CLI interface

Installation​

# Using npm
npm install @hashgraphonline/conversational-agent

# Using pnpm
pnpm add @hashgraphonline/conversational-agent

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

Basic Setup​

1. Environment Configuration​

Create a .env file with your credentials:

# Hedera Configuration
HEDERA_NETWORK=testnet
HEDERA_ACCOUNT_ID=0.0.YOUR_ACCOUNT_ID
HEDERA_PRIVATE_KEY=YOUR_PRIVATE_KEY

# OpenAI Configuration
OPENAI_API_KEY=YOUR_OPENAI_API_KEY

2. Initialize the Agent​

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

dotenv.config();

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

// Initialize the agent
await agent.initialize();

Using the CLI​

The easiest way to get started is with the interactive CLI:

# If installed globally
conversational-agent

# Or using pnpm from the project
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-key
pnpm cli

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

The CLI provides:

  • 🎨 Beautiful terminal interface
  • 💬 Interactive chat with your agent
  • 🔐 Secure credential input
  • 📊 Real-time transaction feedback

Your First Agent Operations​

HCS-10: Register an AI Agent​

const response = await agent.processMessage(
  "Register me as an AI assistant named HelperBot with text generation capabilities and ai tag"
);

console.log(response.response);
// Output: Successfully registered agent HelperBot with account 0.0.123456

HCS-10: Connect to Another Agent​

// Find other agents
const findResponse = await agent.processMessage(
  "Find all agents with ai tag"
);

// Connect to an agent
const connectResponse = await agent.processMessage(
  "Connect to agent 0.0.789012"
);

// Send a message
const messageResponse = await agent.processMessage(
  "Send 'Hello from HelperBot!' to connection 1"
);

HCS-2: Create a Registry​

const response = await agent.processMessage(
  "Create a new HCS-2 topic registry"
);

console.log(response.response);
// Output: Registry created with topic ID 0.0.123457

Inscription: Store Content​

// Inscribe from URL
const inscribeResponse = await agent.processMessage(
  "Inscribe the content from https://example.com/data.json"
);

// Create a Hashinal NFT
const nftResponse = await agent.processMessage(
  "Create a Hashinal NFT with name 'My First NFT' and description 'Created with Conversational Agent'"
);

Understanding the Architecture​

The agent manages three built-in plugins:

// Access plugins directly if needed
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();

State Management​

The agent automatically manages state through OpenConvaiState:

// State is automatically persisted to .env file
// After registering an agent:
// HELPERBOT_ACCOUNT_ID=0.0.123456
// HELPERBOT_PRIVATE_KEY=...
// HELPERBOT_INBOUND_TOPIC_ID=0.0.123457
// HELPERBOT_OUTBOUND_TOPIC_ID=0.0.123458

// The state manager tracks:
// - Registered agents
// - Active connections
// - Registry topics
// - Inscription records

Common Operations​

HCS-10 Agent Communication​

// List your connections
"List my active connections"

// Check for messages
"Check messages from agent 0.0.789012"

// Accept connection requests
"Show pending connection requests"
"Accept connection request 1"

HCS-2 Registry Management​

// Register an entry
"Register topic 0.0.98765 in registry 0.0.123456"

// Query entries
"Query all registered topics from registry 0.0.123456"

// Update an entry
"Register updated version of topic 0.0.98765 in registry 0.0.123456"

Content Inscription​

// Inscribe a file
"Inscribe the file at /path/to/document.pdf"

// Retrieve inscription
"Get inscription details for job ID abc123"

Error Handling​

Always wrap operations in try-catch blocks:

try {
  const response = await agent.processMessage(
    "Register me as an agent named TestBot"
  );
  console.log('Success:', response.response);
} catch (error) {
  console.error('Error:', error.message);
  
  // The agent provides helpful error messages
  if (error.message.includes('already registered')) {
    console.log('Agent already exists with that name');
  }
}

Operational Modes​

Autonomous Mode (Default)​

Agent executes transactions directly:

const agent = new ConversationalAgent({
  // ... other config
  operationalMode: 'autonomous'
});

ReturnBytes Mode​

Returns transaction bytes for external signing:

const agent = new ConversationalAgent({
  // ... other config
  operationalMode: 'returnBytes'
});

const response = await agent.processMessage(
  "Create a topic"
);
// response contains transaction bytes for external signing

Custom Plugins​

You can extend the agent with custom plugins:

import { MyCustomPlugin } from './my-plugin';

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

See the Plugin Development Guide for details.

Next Steps​