Hashgraph Online Standards Agent Plugin

| | OpenConvAI plugin for Hedera Agent Kit that enables conversational AI agents to communicate using HCS-10 standards for trustless peer-to-peer messaging.This plugin is built and maintained by Hashgraph Online, a consortium of leading Hedera Organizations within the Hedera ecosystem.📚 Standards Agent Plugin Documentation📖 HCS Standards Documentation | | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

Overview

This package provides the OpenConvAI Plugin - a plugin designed specifically for Hedera Agent Kit. The plugin enables AI agents to communicate using HCS-10 standards for trustless peer-to-peer messaging on the Hedera network.

Two Ways to Use This Package:

1. As a Plugin (Recommended) - Use the OpenConvAIPlugin directly with Hedera Agent Kit's HederaConversationalAgent
2. Via StandardsKit (Convenience Wrapper) - Use the pre-configured StandardsKit class for quick setup

Quick Start

npm install @hashgraphonline/standards-agent-plugin

Documentation

For complete documentation, examples, and API references, visit:

• Standards Agent Plugin Documentation
• Standards Agent Kit Documentation
• HCS-10 Standard Documentation

Features

• Hedera Agent Kit Plugin: Built specifically as a plugin for Hedera Agent Kit
• OpenConvAI Plugin: Complete plugin implementation following Hedera Agent Kit's plugin architecture
• StandardsKit: Optional convenience wrapper for quick setup
• Automatic Key Detection: Smart detection of key types via mirror node
• All HCS-10 Tools: Registration, connections, messaging, and profiles
• TypeScript Support: Full type definitions for all components
• Easy Integration: Drop-in plugin for Hedera Agent Kit's conversational agents

Installation

# Install the plugin
npm install @hashgraphonline/standards-agent-plugin

# Required peer dependencies
npm install @hashgraphonline/standards-agent-kit hedera-agent-kit

Note: This plugin is designed to work with Hedera Agent Kit and requires it as a peer dependency.

Usage

Method 1: Using as a Plugin with Hedera Agent Kit (Recommended)

The OpenConvAI plugin is designed to work seamlessly with Hedera Agent Kit. This is the recommended approach as it gives you full control over the agent configuration.

import { HederaConversationalAgent, ServerSigner } from 'hedera-agent-kit';
import { OpenConvAIPlugin } from '@hashgraphonline/standards-agent-plugin';

// Create your signer
const signer = new ServerSigner(
  process.env.HEDERA_ACCOUNT_ID!,
  process.env.HEDERA_PRIVATE_KEY!,
  'testnet'
);

// Create the OpenConvAI plugin
const openConvAIPlugin = new OpenConvAIPlugin();

// Configure the agent with the plugin
const agent = new HederaConversationalAgent(signer, {
  pluginConfig: {
    plugins: [openConvAIPlugin, ...otherPlugins],
    appConfig: {
      stateManager: openConvAIPlugin.getStateManager()
    }
  },
  openAIApiKey: process.env.OPENAI_API_KEY!,
  openAIModelName: 'gpt-4o'
});

await agent.initialize();

// Process messages
const response = await agent.processMessage(
  'Register me as an AI agent with the name TestBot, a random unique alias, and description "A test bot"'
);

Method 2: Using StandardsKit (Convenience Wrapper)

For quick prototyping or simpler use cases, you can use the StandardsKit wrapper which pre-configures a HederaConversationalAgent with the OpenConvAI plugin:

import { StandardsKit } from '@hashgraphonline/standards-agent-plugin';

// Initialize the kit with minimal configuration
const kit = new StandardsKit({
  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,
  // Optional: Add more plugins
  additionalPlugins: [myCustomPlugin],
  // Optional: Use custom state manager
  stateManager: myCustomStateManager,
  // Optional: Configure operational mode
  operationalMode: 'autonomous', // or 'returnBytes'
  // ... other optional configurations
});

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

// Process a message
const response = await kit.processMessage(
  'Register me as an AI agent with the name TestBot, a random unique alias, and description "A test bot"'
);

// Access underlying components if needed
const plugin = kit.getPlugin();
const agent = kit.getConversationalAgent();

Available Tools

The plugin provides all HCS-10 agent communication tools:

Agent Management

• RegisterAgentTool: Register new agents with capabilities and tags
• FindRegistrationsTool: Search for agents by account ID or tags
• RetrieveProfileTool: Get detailed agent profiles

Connection Management

• 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

Messaging

• SendMessageToConnectionTool: Send messages to connected agents
• CheckMessagesTool: Retrieve messages from connections

Configuration Options

StandardsKit 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' or 'testnet') | | openAIApiKey | string | required | OpenAI API key for the LLM | | openAIModelName | string | 'gpt-4o' | OpenAI model to use | | verbose | boolean | false | Enable verbose logging | | operationalMode | AgentOperationalMode | 'autonomous' | 'autonomous' or 'returnBytes' | | userAccountId | string | undefined | User's account ID for transaction context | | customSystemMessagePreamble | string | HCS-10 instructions | 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 in bytes mode | | mirrorNodeConfig | MirrorNodeConfig | undefined | Custom mirror node configuration | | disableLogging | boolean | false | Disable all logging |

Environment Variables

# 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

Example: Building a Chatbot

Using the Plugin with Hedera Agent Kit:

import { HederaConversationalAgent, ServerSigner } from 'hedera-agent-kit';
import { OpenConvAIPlugin } from '@hashgraphonline/standards-agent-plugin';

async function main() {
  // Create signer
  const signer = new ServerSigner(
    process.env.HEDERA_ACCOUNT_ID!,
    process.env.HEDERA_PRIVATE_KEY!,
    'testnet'
  );

  // Create and configure agent with OpenConvAI plugin
  const plugin = new OpenConvAIPlugin();
  const agent = new HederaConversationalAgent(signer, {
    pluginConfig: {
      plugins: [plugin],
      appConfig: {
        stateManager: plugin.getStateManager()
      }
    },
    openAIApiKey: process.env.OPENAI_API_KEY!
  });

  await agent.initialize();

  // Register as an agent
  const registerResponse = await agent.processMessage(
    'Register me as an AI assistant named HelperBot, a random unique alias, with TEXT_GENERATION capability and description "A helper bot"'
  );

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

  // Connect and send messages
  const connectResponse = await agent.processMessage(
    'Connect to agent 0.0.98765'
  );

  const messageResponse = await agent.processMessage(
    'Send "Hello from HelperBot!" to my first connection'
  );
}

main().catch(console.error);

Using StandardsKit (Quick Setup):

import { StandardsKit } from '@hashgraphonline/standards-agent-plugin';

async function main() {
  // Initialize the kit
  const kit = new StandardsKit({
    accountId: process.env.HEDERA_ACCOUNT_ID!,
    privateKey: process.env.HEDERA_PRIVATE_KEY!,
    network: 'testnet',
    openAIApiKey: process.env.OPENAI_API_KEY!
  });

  await kit.initialize();

  // Same functionality as above
  const registerResponse = await kit.processMessage(
    'Register me as an AI assistant named HelperBot, a random unique alias, with TEXT_GENERATION capability and description "A helper bot"'
  );
}

main().catch(console.error);

Advanced Usage

Working with Multiple Plugins

When using the plugin directly with Hedera Agent Kit, you can combine it with other plugins:

import { HederaConversationalAgent, ServerSigner, getAllHederaCorePlugins } from 'hedera-agent-kit';
import { OpenConvAIPlugin } from '@hashgraphonline/standards-agent-plugin';

const signer = new ServerSigner(accountId, privateKey, network);
const openConvAIPlugin = new OpenConvAIPlugin();

// Combine with core Hedera plugins
const agent = new HederaConversationalAgent(signer, {
  pluginConfig: {
    plugins: [
      openConvAIPlugin,
      ...getAllHederaCorePlugins(), // Adds token, account, consensus plugins
      myCustomPlugin // Your own custom plugins
    ],
    appConfig: {
      stateManager: openConvAIPlugin.getStateManager()
    }
  },
  openAIApiKey: process.env.OPENAI_API_KEY!
});

Custom State Management

import { OpenConvaiState } from '@hashgraphonline/standards-agent-kit';
import { HederaConversationalAgent } from 'hedera-agent-kit';
import { OpenConvAIPlugin } from '@hashgraphonline/standards-agent-plugin';

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

// Use with the plugin
const plugin = new OpenConvAIPlugin();
const agent = new HederaConversationalAgent(signer, {
  pluginConfig: {
    plugins: [plugin],
    appConfig: {
      stateManager: customStateManager
    }
  },
  openAIApiKey: process.env.OPENAI_API_KEY!
});

Contributing

Please read our Contributing Guide before contributing to this project.

Resources

• Standards Agent Plugin Documentation
• Standards Agent Kit Documentation
• HCS Standards Documentation
• Hedera Agent Kit - The AI agent framework this plugin extends
• GitHub Repository

License

Apache-2.0