@hashgraphonline/standards-agent-kit 0.0.38 → 0.2.1

package/README.md

@@ -1,15 +1,22 @@
-# Hashgraph Online Standards AI Agent Kit
+# Hashgraph Online Standards Agent Kit
 
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+| ![](https://hashgraphonline.com/img/logo.png) | A modular SDK for building on-chain autonomous agents using Hashgraph Online Standards, including HCS-10 for agent discovery and communication.<br><br>This SDK is built and maintained by [Hashgraph Online](https://hashgraphonline.com), a consortium of leading Hedera Organizations within the Hedera ecosystem.<br><br>[📚 Standards Agent Kit Documentation](https://hashgraphonline.com/docs/libraries/standards-agent-kit/)<br>[📖 HCS Standards Documentation](https://hcs-improvement-proposals.pages.dev/docs/standards) |
+| :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 
-# **_This SDK is currently in alpha, use at your own risk._**
+## Quick Start
 
-A toolkit built with TypeScript and LangChain for creating AI agents that communicate trustlessly on the Hedera network using the [HCS-10 AI Agent Communication Standard](https://hashgraphonline.com/docs/standards/hcs-10/).
+```bash
+npm install @hashgraphonline/standards-agent-kit
+```
 
-## Quick Start
+## Installation
 
 ```bash
+# Install the core SDK
 npm install @hashgraphonline/standards-agent-kit
+
+# Optional: Install the OpenConvAI plugin for additional functionality
+npm install @hashgraphonline/standards-agent-plugin
 ```
 
 ## Documentation
@@ -17,216 +24,176 @@ npm install @hashgraphonline/standards-agent-kit
 For complete documentation, examples, and API references, visit:
 
 - [Standards Agent Kit Documentation](https://hashgraphonline.com/docs/libraries/standards-agent-kit/)
+- [HCS-10 Standard Documentation](https://hcs-improvement-proposals.pages.dev/docs/standards/hcs-10)
 
 ## Features
 
-- **HCS-10 Compliance:** Built on top of the official `@hashgraphonline/standards-sdk` for standard compliance.
-- **Agent Lifecycle Management:** Create, register, and manage HCS-10 agents on Hedera.
-- **Trustless Communication:** Facilitates secure peer-to-peer communication setup between agents via Hedera Consensus Service (HCS).
-- **LangChain Integration:** Provides ready-to-use LangChain `StructuredTool`s for common agent actions.
-- **Message Handling:** Send and receive messages over HCS, including support for large messages via HCS-3 inscriptions.
-- **Connection Monitoring:** Automatically monitor inbound topics for connection requests and handle them.
-- **Configurable:** Set Hedera network, credentials, and registry via environment variables.
-
-## Supported Tools
-
-- **RegisterAgentTool**: Create and register a new HCS-10 agent
-- **SendMessageTool**: Send messages to a topic with optional response monitoring
-- **ConnectionTool**: Monitor inbound topics for connection requests
-- **FindRegistrationsTool**: Search for agent registrations by criteria
-- **InitiateConnectionTool**: Start a connection with another agent
-- **ListConnectionsTool**: View existing agent connections
-- **ConnectionMonitorTool**: Monitor connection status changes
-- **ManageConnectionRequestsTool**: Handle incoming connection requests
-- **AcceptConnectionRequestTool**: Accept pending connection requests
-- **ListUnapprovedConnectionRequestsTool**: View pending requests
+- **HCS-10 Agent Tools**: Complete toolkit for agent registration, discovery, and communication
+- **Plugin System**: Extensible architecture for adding custom capabilities
+- **LangChain Integration**: Seamless integration with LangChain for AI agent development
+- **Built on Hedera Agent Kit**: Leverages the powerful Hedera Agent Kit for blockchain interactions
+- **OpenConvAI Plugin Support**: Pre-built integration with the OpenConvAI standards plugin
+- **TypeScript Support**: Full TypeScript support with comprehensive type definitions
+- **State Management**: Built-in state management for agent operations
 
-## Running Demos
+## Usage
 
-The Agent Kit includes demo implementations that showcase various features. Follow these steps to run them:
+### Basic Setup with LangChain
 
-1. Clone the repository
+```typescript
+import { HederaAgentKit } from 'hedera-agent-kit';
+import { 
+  RegisterAgentTool,
+  FindRegistrationsTool,
+  InitiateConnectionTool,
+  SendMessageToConnectionTool,
+  HCS10Builder,
+  OpenConvaiState
+} from '@hashgraphonline/standards-agent-kit';
+
+// Initialize HederaAgentKit
+const hederaKit = new HederaAgentKit({
+  accountId: process.env.HEDERA_ACCOUNT_ID,
+  privateKey: process.env.HEDERA_PRIVATE_KEY,
+  network: 'testnet'
+});
+
+// Create state manager and builder
+const stateManager = new OpenConvaiState();
+const hcs10Builder = new HCS10Builder(hederaKit, stateManager);
+
+// Create tools
+const tools = [
+  new RegisterAgentTool({ hederaKit, hcs10Builder }),
+  new FindRegistrationsTool({ hederaKit, hcs10Builder }),
+  new InitiateConnectionTool({ hederaKit, hcs10Builder }),
+  new SendMessageToConnectionTool({ hederaKit, hcs10Builder })
+];
+
+// Use tools with LangChain
+import { ChatOpenAI } from '@langchain/openai';
+import { createToolCallingAgent } from 'langchain/agents';
+
+const llm = new ChatOpenAI({
+  modelName: 'gpt-4',
+  openAIApiKey: process.env.OPENAI_API_KEY
+});
+
+const agent = await createToolCallingAgent({
+  llm,
+  tools,
+  prompt: /* your prompt */
+});
+```
+
+### Using with OpenConvAI Plugin
+
+```typescript
+import { StandardsKit } from '@hashgraphonline/standards-agent-plugin';
+
+// Initialize StandardsKit with OpenConvAI plugin pre-configured
+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();
+
+// Use the conversational agent
+const response = await kit.processMessage('Find all registered AI agents');
+```
+
+## Running Examples
+
+1. Clone the repository
    ```bash
-   git clone https://github.com/hashgraph/standards-agent-kit.git
+   git clone https://github.com/hashgraph-online/standards-agent-kit.git
    cd standards-agent-kit
    ```
 
 2. Install dependencies
-
    ```bash
-   npm install --legacy-peer-deps
+   pnpm install
    ```
 
 3. Set up environment variables
-
    ```bash
-   cp .env.sample .env
+   cp .env.example .env
    ```
 
 4. Edit the `.env` file with your Hedera credentials:
-
    ```
-   HEDERA_ACCOUNT_ID=0.0.xxxxxx
-   HEDERA_PRIVATE_KEY=302e020100300506032b6570...
+   HEDERA_ACCOUNT_ID=0.0.12345
+   HEDERA_PRIVATE_KEY=your_private_key_here
    HEDERA_NETWORK=testnet
-   REGISTRY_URL=https://moonscape.tech
-   OPENAI_API_KEY=sk-xxxxxxxxxx  # For LangChain demos
+   OPENAI_API_KEY=your_openai_key_here  # Required for AI demos
    ```
 
-5. Run the demos:
-
+5. Run the examples:
    ```bash
-   # Run the CLI demo
-   npm run cli-demo
-
-   # Run the LangChain interactive demo
-   npm run langchain-demo
-   
-   # Run the Standards Expert Agent
-   npm run standards-expert
-   ```
+   # Interactive CLI demo
+   npm run demo:cli
 
-### Demo Descriptions
+   # LangChain integration demo
+   npm run demo:langchain
 
-#### CLI Demo
+   # Plugin system example
+   npm run demo:plugin
 
-The CLI demo provides an interactive menu to:
-- Register new agents
-- List managed agents
-- Initiate and monitor connections
-- Send and receive messages between agents
+   # OpenConvAI plugin example
+   npm run demo:plugin:openconvai
+   ```
 
-#### LangChain Interactive Demo
+## Available Tools
 
-The LangChain demo demonstrates how to:
-- Integrate Standards Agent Kit tools with LangChain
-- Create AI agents that communicate over Hedera
-- Process natural language requests into agent actions
-- Handle the full lifecycle of agent-to-agent communication
+The SDK provides a comprehensive set of tools for HCS-10 agent operations:
 
-#### Standards Expert Agent
+- **RegisterAgentTool**: Register new agents on the network
+- **FindRegistrationsTool**: Search for registered agents
+- **RetrieveProfileTool**: Get detailed agent profiles
+- **InitiateConnectionTool**: Start connections between agents
+- **ListConnectionsTool**: View active connections
+- **SendMessageToConnectionTool**: Send messages to connected agents
+- **CheckMessagesTool**: Retrieve messages from connections
+- **ConnectionMonitorTool**: Monitor incoming connection requests
+- **ManageConnectionRequestsTool**: Handle pending connections
+- **AcceptConnectionRequestTool**: Accept incoming connections
+- **ListUnapprovedConnectionRequestsTool**: View pending requests
 
-A specialized agent that runs on a small local LLM to provide expertise about Hedera Standards:
-- Uses Llama 3 8B or similar for inference
-- Answers questions about standards implementation
-- Provides guidance on Standards SDK and Agent Kit usage
-- See [Standards Expert README](examples/standards-expert/README.md) for details
+## Plugin Development
 
-## Basic Usage
+Create custom plugins by extending the base plugin interface:
 
 ```typescript
-import { initializeHCS10Client } from '@hashgraphonline/standards-agent-kit';
-import dotenv from 'dotenv';
-
-dotenv.config();
-
-async function setup() {
-  const { hcs10Client, tools, stateManager } = await initializeHCS10Client({
-    clientConfig: {
-      operatorId: process.env.HEDERA_ACCOUNT_ID,
-      operatorKey: process.env.HEDERA_PRIVATE_KEY,
-      network: 'testnet',
-      useEncryption: false
-    },
-    createAllTools: true,
-    monitoringClient: true
-  });
-
-  // Access tools
-  const { registerAgentTool, initiateConnectionTool, sendMessageTool } = tools;
+import { BasePlugin } from '@hashgraphonline/standards-agent-kit';
+
+export class MyCustomPlugin extends BasePlugin {
+  name = 'my-custom-plugin';
+  
+  async initialize(context) {
+    // Initialize your plugin
+  }
   
-  // Use tools as needed
-  // ...
+  getTools() {
+    // Return your custom tools
+  }
 }
-
-setup();
 ```
 
-For detailed usage examples and API reference, please refer to the [official documentation](https://hashgraphonline.com/docs/libraries/standards-agent-kit/).
+## Contributing
+
+Please read our [Contributing Guide](CONTRIBUTING.md) before contributing to this project.
 
 ## Resources
 
-- [HCS Standards Documentation](https://hashgraphonline.com/docs/standards/)
+- [Standards Agent Kit Documentation](https://hashgraphonline.com/docs/libraries/standards-agent-kit/)
+- [HCS Standards Documentation](https://hcs-improvement-proposals.pages.dev/docs/standards)
 - [Hedera Documentation](https://docs.hedera.com)
-- [Standards SDK](https://hashgraphonline.com/docs/libraries/standards-sdk/)
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.
+- [GitHub Repository](https://github.com/hashgraph-online/standards-agent-kit)
 
 ## License
 
 Apache-2.0
 
-## Standards Expert Agent
-
-The Standards Expert Agent is a specialized AI agent that runs on a small local LLM and can answer questions about the Hedera Standards SDK. It uses the HCS-10 protocol to communicate with clients and provides information about how to use the Standards SDK and Standards Agent Kit.
-
-### Features
-
-- Runs on a small local LLM (Llama 3 8B or similar)
-- Focused knowledge on Hedera Standards SDK
-- Answers questions about HCS-1, HCS-2, HCS-3, etc.
-- Provides implementation guidance for standards
-- Self-contained with minimal external dependencies
-
-### Installation
-
-```bash
-# Clone the repository
-git clone https://github.com/hashgraph/standards-agent-kit.git
-cd standards-agent-kit
-
-# Install dependencies
-npm install
-
-# Set up the environment
-npx ts-node src/agents/standards-expert/cli.ts setup
-
-# Download a Llama 3 model in GGUF format
-mkdir -p models
-# Download the model from https://huggingface.co/TheBloke/Llama-3-8B-Instruct-GGUF
-# and place it in the models directory
-
-# Process documentation (optional)
-npx ts-node src/agents/standards-expert/cli.ts process-docs -d /path/to/docs
-
-# Start the agent
-npx ts-node src/agents/standards-expert/cli.ts start
-```
-
-### Using with PM2
-
-For production deployment, you can use PM2 to keep the agent running:
-
-```bash
-# Generate PM2 ecosystem file
-npx ts-node src/agents/standards-expert/cli.ts generate-pm2
-
-# Install PM2 globally
-npm install -g pm2
-
-# Start with PM2
-pm2 start ecosystem.config.js
-```
-
-### Environment Variables
-
-Create a `.env` file with the following variables:
-
-```
-# Hedera Account Information
-HEDERA_ACCOUNT_ID=0.0.123456
-HEDERA_PRIVATE_KEY=302e...
-
-# Agent HCS Topics
-AGENT_INBOUND_TOPIC_ID=0.0.123456
-AGENT_OUTBOUND_TOPIC_ID=0.0.123457
-
-# Vector Store Configuration
-OPENAI_API_KEY=sk-...
-
-# Model Configuration
-LLAMA_MODEL_PATH=./models/llama-3-8b-instruct.Q4_K_M.gguf
-```

package/dist/cjs/builders/hcs10/hcs10-builder.d.ts

@@ -0,0 +1,262 @@
+import { BaseServiceBuilder, HederaAgentKit } from 'hedera-agent-kit';
+import { PrivateKey, TransactionReceipt } from '@hashgraph/sdk';
+import { IStateManager } from '../../state/state-types';
+import { ExecuteResult } from '../types';
+import { FeeConfigBuilderInterface, HCS10Client, ProfileResponse as SDKProfileResponse, HCSMessage, LogLevel, HandleConnectionRequestResponse } from '@hashgraphonline/standards-sdk';
+/**
+ * Message response with timestamp
+ */
+export interface HCSMessageWithTimestamp extends Omit<HCSMessage, 'op'> {
+    timestamp: number;
+    data?: string;
+    sequence_number: number;
+    op?: HCSMessage['op'] | string;
+    operator_id?: string;
+    created?: Date;
+    m?: string;
+}
+/**
+ * Network type for HCS-10
+ */
+export type StandardNetworkType = 'mainnet' | 'testnet';
+/**
+ * Parameters for agent registration
+ */
+export interface RegisterAgentParams {
+    name: string;
+    bio?: string;
+    alias?: string;
+    type?: 'autonomous' | 'manual';
+    model?: string;
+    capabilities?: number[];
+    creator?: string;
+    socials?: Record<string, string>;
+    properties?: Record<string, unknown>;
+    profilePicture?: string | {
+        url?: string;
+        path?: string;
+        filename?: string;
+    };
+    existingProfilePictureTopicId?: string;
+    initialBalance?: number;
+    userAccountId?: string;
+    hbarFee?: number;
+    tokenFees?: Array<{
+        amount: number;
+        tokenId: string;
+    }>;
+    exemptAccountIds?: string[];
+}
+/**
+ * Parameters for initiating a connection
+ */
+export interface InitiateConnectionParams {
+    targetAccountId: string;
+    disableMonitor?: boolean;
+    memo?: string;
+}
+/**
+ * Parameters for accepting a connection request
+ */
+export interface AcceptConnectionParams {
+    requestKey: string;
+    hbarFee?: number | undefined;
+    exemptAccountIds?: string[] | undefined;
+}
+/**
+ * Parameters for sending a message
+ */
+export interface SendMessageParams {
+    topicId: string;
+    message: string;
+    disableMonitoring?: boolean;
+}
+/**
+ * Parameters for sending a message to a connected account
+ */
+export interface SendMessageToConnectionParams {
+    targetIdentifier: string;
+    message: string;
+    disableMonitoring?: boolean;
+}
+/**
+ * HCS10Builder facilitates HCS-10 protocol operations for agent communication
+ * This builder incorporates all HCS10Client functionality directly
+ */
+export declare class HCS10Builder extends BaseServiceBuilder {
+    private standardClient;
+    private stateManager;
+    private executeResult?;
+    private useEncryption;
+    private guardedRegistryBaseUrl;
+    private network;
+    private sdkLogger;
+    constructor(hederaKit: HederaAgentKit, stateManager?: IStateManager, options?: {
+        useEncryption?: boolean;
+        registryUrl?: string;
+        logLevel?: LogLevel;
+    });
+    /**
+     * Get the operator account ID
+     */
+    getOperatorId(): string;
+    /**
+     * Get the network type
+     */
+    getNetwork(): StandardNetworkType;
+    /**
+     * Get account and signer information
+     */
+    getAccountAndSigner(): {
+        accountId: string;
+        signer: PrivateKey;
+    };
+    /**
+     * Get the inbound topic ID for the current operator
+     */
+    getInboundTopicId(): Promise<string>;
+    /**
+     * Get agent profile
+     */
+    getAgentProfile(accountId: string): Promise<SDKProfileResponse>;
+    /**
+     * Submit connection request
+     */
+    submitConnectionRequest(inboundTopicId: string, memo: string): Promise<TransactionReceipt>;
+    /**
+     * Handle connection request
+     */
+    handleConnectionRequest(inboundTopicId: string, requestingAccountId: string, connectionRequestId: number, feeConfig?: FeeConfigBuilderInterface): Promise<HandleConnectionRequestResponse>;
+    /**
+     * Send message to a topic
+     */
+    sendMessage(topicId: string, data: string, memo?: string): Promise<{
+        sequenceNumber: number | undefined;
+        receipt: TransactionReceipt;
+        transactionId: string | undefined;
+    }>;
+    /**
+     * Get messages from a topic
+     */
+    getMessages(topicId: string): Promise<{
+        messages: HCSMessageWithTimestamp[];
+    }>;
+    /**
+     * Get message stream from a topic
+     */
+    getMessageStream(topicId: string): Promise<{
+        messages: HCSMessage[];
+    }>;
+    /**
+     * Get message content
+     */
+    getMessageContent(inscriptionIdOrData: string): Promise<string>;
+    /**
+     * Get the standard client instance (for compatibility)
+     */
+    getStandardClient(): HCS10Client;
+    /**
+     * Load profile picture from URL or file path
+     */
+    private loadProfilePicture;
+    /**
+     * Create and register an agent
+     */
+    private createAndRegisterAgent;
+    /**
+     * Register a new HCS-10 agent
+     * Note: This performs multiple transactions and requires directExecution mode
+     */
+    registerAgent(params: RegisterAgentParams): Promise<this>;
+    /**
+     * Initiate a connection to another agent
+     */
+    initiateConnection(params: InitiateConnectionParams): Promise<this>;
+    /**
+     * Accept a connection request
+     * Note: This performs multiple transactions and requires directExecution mode
+     */
+    acceptConnection(params: AcceptConnectionParams): Promise<this>;
+    /**
+     * Send a message using HCS (for operations that need direct topic access)
+     */
+    sendHCS10Message(params: SendMessageParams): Promise<this>;
+    /**
+     * Send a message to a connected account with optional response monitoring
+     */
+    sendMessageToConnection(params: SendMessageToConnectionParams): Promise<this>;
+    /**
+     * Monitor responses on a topic after sending a message
+     */
+    private monitorResponses;
+    /**
+     * Start passive monitoring for incoming connection requests
+     * This method monitors continuously in the background
+     */
+    startPassiveConnectionMonitoring(): Promise<this>;
+    /**
+     * Monitor for incoming connection requests
+     */
+    monitorConnections(params: {
+        acceptAll?: boolean;
+        targetAccountId?: string;
+        monitorDurationSeconds?: number;
+        hbarFees?: Array<{
+            amount: number;
+            collectorAccount?: string;
+        }>;
+        tokenFees?: Array<{
+            amount: number;
+            tokenId: string;
+            collectorAccount?: string;
+        }>;
+        exemptAccountIds?: string[];
+        defaultCollectorAccount?: string;
+    }): Promise<this>;
+    /**
+     * Manage connection requests (list, view, or reject)
+     */
+    manageConnectionRequests(params: {
+        action: 'list' | 'view' | 'reject';
+        requestKey?: string;
+    }): Promise<this>;
+    /**
+     * List unapproved connection requests
+     */
+    listUnapprovedConnectionRequests(): Promise<this>;
+    /**
+     * List connections with enhanced details
+     */
+    listConnections(params?: {
+        includeDetails?: boolean;
+        showPending?: boolean;
+    }): Promise<this>;
+    private formatConnection;
+    private getEnhancedConnections;
+    /**
+     * Check messages on a connection
+     */
+    checkMessages(params: {
+        targetIdentifier: string;
+        fetchLatest?: boolean;
+        lastMessagesCount?: number;
+    }): Promise<this>;
+    /**
+     * Find registrations using the configured registry
+     */
+    findRegistrations(params: {
+        accountId?: string;
+        tags?: number[];
+    }): Promise<this>;
+    /**
+     * Retrieve detailed profile information for an agent
+     */
+    retrieveProfile(params: {
+        accountId: string;
+        disableCache?: boolean;
+    }): Promise<this>;
+    /**
+     * Override execute to return stored HCS10 operation results
+     */
+    execute(): Promise<ExecuteResult>;
+}

package/dist/cjs/builders/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './hcs10/hcs10-builder';

package/dist/cjs/builders/types.d.ts

@@ -0,0 +1,10 @@
+import { TransactionReceipt } from '@hashgraph/sdk';
+export interface ExecuteResult {
+    success: boolean;
+    receipt?: TransactionReceipt;
+    scheduleId?: string;
+    error?: string;
+    transactionId?: string | undefined;
+    rawResult?: unknown;
+    notes?: string[];
+}

package/dist/cjs/index.d.ts

@@ -1,5 +1,7 @@
-export * from './hcs10';
 export * from './tools';
 export * from './state';
 export * from './init';
 export * from './plugins';
+export { HCS10Builder } from './builders';
+export type { ExecuteResult } from './builders';
+export { HCS10Client } from './hcs10';