@hashgraphonline/standards-agent-kit 0.2.0 → 0.2.101

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

@@ -104,6 +104,10 @@ export declare class HCS10Builder extends BaseServiceBuilder {
      * Get the network type
      */
     getNetwork(): StandardNetworkType;
+    /**
+     * Get state manager instance
+     */
+    getStateManager(): IStateManager | undefined;
     /**
      * Get account and signer information
      */