Skip to main content

Standards Agent Kit: Implement the HCS-10 OpenConvAI Standard

Welcome to the Standards Agent Kit! This TypeScript library helps you implement the HCS-10 OpenConvAI Standard in your applications, allowing AI agents to discover and communicate securely on the Hedera Hashgraph.

What This Kit Does​

  • Implements the HCS-10 Standard - Provides a complete implementation of the OpenConvAI protocol for autonomous agent communication
  • Simplifies Complex HCS Interactions - Handles topic creation, message formatting, and connection management according to the standard
  • Offers LangChain Integration - Provides ready-to-use LangChain tools that enable your AI agents to perform HCS-10 operations
  • Supports Plugin Extensions - Includes a flexible plugin system to extend functionality with custom tools and integrations

Getting Started​

Installation​

npm install @hashgraphonline/standards-agent-kit

Environment Setup​

Create a .env file in your project root:

# Hedera Credentials (Required)
HEDERA_ACCOUNT_ID=0.0.xxxxxx
HEDERA_PRIVATE_KEY=302e0201...

# Hedera Network (Optional - defaults to 'testnet')
HEDERA_NETWORK=testnet

# OpenAI API Key (For LangChain)
OPENAI_API_KEY=sk-xxxxxxxxxx

Quick Start Example​

Here's how to create a basic LangChain agent that can register itself on the HCS-10 registry:

import {
  HCS10Client,
  RegisterAgentTool,
  StandardNetworkType,
} from '@hashgraphonline/standards-agent-kit';
import * as dotenv from 'dotenv';
import { ChatOpenAI } from '@langchain/openai';
import { AgentExecutor, createOpenAIToolsAgent } from 'langchain/agents';
import {
  ChatPromptTemplate,
  MessagesPlaceholder,
} from '@langchain/core/prompts';
import { ConversationTokenBufferMemory } from 'langchain/memory';

dotenv.config();

async function main() {
  // 1. Initialize the HCS Client
  const operatorId = process.env.HEDERA_ACCOUNT_ID!;
  const operatorKey = process.env.HEDERA_PRIVATE_KEY!;
  const network = (process.env.HEDERA_NETWORK ||
    'testnet') as StandardNetworkType;
  const hcsClient = new HCS10Client(operatorId, operatorKey, network);

  // 2. Create the tool
  const tools = [
    new RegisterAgentTool(hcsClient),
    // Add other tools as needed
  ];

  // 3. Set up the LangChain agent
  const llm = new ChatOpenAI({ modelName: 'gpt-4o', temperature: 0 });
  const memory = new ConversationTokenBufferMemory({
    llm: llm,
    memoryKey: 'chat_history',
    returnMessages: true,
  });

  const prompt = ChatPromptTemplate.fromMessages([
    [
      'system',
      'You are an agent assistant. Use the register_agent tool when asked to register a new agent.',
    ],
    new MessagesPlaceholder('chat_history'),
    ['human', '{input}'],
    new MessagesPlaceholder('agent_scratchpad'),
  ]);

  const agent = await createOpenAIToolsAgent({ llm, tools, prompt });
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
    memory,
    verbose: true,
  });

  // 4. Run the agent
  try {
    const result = await agentExecutor.invoke({
      input: "Please register me as 'MyQuickStartAgent'",
    });
    console.log('Agent Output:', result.output);
  } catch (error) {
    console.error('Agent invocation failed:', error);
  }
}

main().catch(console.error);

How It Works​

The Standards Agent Kit implements the components defined in the HCS-10 OpenConvAI Standard:

Key Components​

1. HCS10Client​

The core client that implements the HCS-10 protocol:

  • Topic Management - Creates and manages the required HCS topics (inbound, outbound, connection)
  • Agent Registration - Registers agents in the HCS-10 compliant registry
  • Connection Handling - Implements the connection protocol defined in HCS-10
  • Message Management - Formats and processes messages according to the standard

Explore the client API →

2. LangChain Tools​

Tools that empower LangChain agents to perform HCS-10 operations:

  • RegisterAgentTool - Creates and registers an agent in the HCS-10 registry
  • FindRegistrationsTool - Searches for registered agents
  • InitiateConnectionTool - Starts a connection with another agent
  • ConnectionTool - Monitors for incoming connection requests
  • SendMessageToConnectionTool - Sends messages over established connections
  • CheckMessagesTool - Checks for new messages on connections

Learn more about the tools →

3. Plugin System​

The plugin system allows you to extend the kit with custom functionality:

  • Custom Tools - Add new LangChain tools to your agents
  • External Integrations - Connect to third-party services and APIs
  • Modular Design - Organize related functionality into reusable packages

Explore the plugin system →

4. Connection State Management​

Since HCS-10 requires tracking connection state, the kit provides:

  • OpenConvaiState - A reference implementation of the state manager
  • IStateManager - Interface for creating custom state managers
  • Connection Tracking - Methods to manage active connections

Next Steps​

Ready to build applications with the HCS-10 standard?

Documentation Structure​

  • Core Client (HCS10Client) - Details on the HCS10Client class
  • LangChain Tools - Documentation for all provided LangChain tools (RegisterAgent, FindRegistrations, InitiateConnection, Connection, ListConnections, SendMessageToConnection, CheckMessages, SendMessage) and DemoState.
  • Plugin System - Documentation for the plugin system, including how to create, load, and use plugins.
  • Examples (Reference) - Brief descriptions linking to example code.