@hashgraphonline/standards-agent-kit/README.md

A modular SDK for building on-chain autonomous agents using Hashgraph Online Standards, including HCS-10 for agent discovery and communication. https://hol.org

# Hashgraph Online Standards Agent Kit

| ![](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://hashgraphonline.com/docs/standards) |
| :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## Quick Start

```bash
npm install @hashgraphonline/standards-agent-kit
```

## 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

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://hashgraphonline.com/docs/standards/hcs-10)

## Features

- **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

## Usage

### Basic Setup with LangChain

```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-online/standards-agent-kit.git
   cd standards-agent-kit
   ```

2. Install dependencies
   ```bash
   pnpm install
   ```

3. Set up environment variables
   ```bash
   cp .env.example .env
   ```

4. Edit the `.env` file with your Hedera credentials:
   ```
   HEDERA_ACCOUNT_ID=0.0.12345
   HEDERA_PRIVATE_KEY=your_private_key_here
   HEDERA_NETWORK=testnet
   OPENAI_API_KEY=your_openai_key_here  # Required for AI demos
   ```

5. Run the examples:
   ```bash
   # Interactive CLI demo
   npm run demo:cli

   # LangChain integration demo
   npm run demo:langchain

   # Plugin system example
   npm run demo:plugin

   # OpenConvAI plugin example
   npm run demo:plugin:openconvai
   ```

## Available Tools

The SDK provides a comprehensive set of tools for HCS-10 agent operations:

- **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

## Registry Broker Plugin

The `RegistryBrokerPlugin` bridges the [`RegistryBrokerClient`](https://hashgraphonline.com/docs/registry-broker/api/client) inside every Hedera Agent Kit integration. Once registered, agents can call *any* broker endpoint (search, chat, registration, UAID utilities, ledger auth, credits, encryption) through a single tool. The plugin automatically reuses shared credentials and keeps encrypted chat handles alive via `conversation.*` operations.

```ts
import { PluginRegistry } from 'hedera-agent-kit';
import { RegistryBrokerPlugin } from '@hashgraphonline/standards-agent-kit';

const pluginRegistry = new PluginRegistry();
pluginRegistry.register(
  new RegistryBrokerPlugin(),
);
```

Configure credentials via `registryBroker` plugin config or environment variables:

```ts
const plugin = new RegistryBrokerPlugin();
await plugin.initialize({
  config: {
    hederaKit,
    registryBroker: {
      client: {
        baseUrl: process.env.REGISTRY_BROKER_BASE_URL,
        apiKey: process.env.REGISTRY_BROKER_API_KEY,
      },
    },
  },
  logger,
});
```

> **Env Fallbacks**
>
> - `REGISTRY_BROKER_API_KEY` / `RB_API_KEY`
> - `REGISTRY_BROKER_BASE_URL`
> - `REGISTRY_BROKER_LEDGER_ACCOUNT_ID`, `REGISTRY_BROKER_LEDGER_NETWORK`, `REGISTRY_BROKER_LEDGER_PRIVATE_KEY` (or `HEDERA_ACCOUNT_ID` / `HEDERA_PRIVATE_KEY`) – enables automatic ledger authentication if no API key is supplied.

Every operation is invoked through `registry_broker_operation`:

```ts
const [registryTool] = plugin.getTools();

// Discovery
await registryTool._call({
  operation: 'search',
  payload: { q: 'openrouter', limit: 5 },
});

// Chat with broker-managed UAIDs
const session = await registryTool._call({
  operation: 'chat.createSession',
  payload: {
    uaid: 'uaid:aid:2bnewJwP95isoCUkT5mee5gm212WS76tphHwBQvbWoquRa9kt89UanrBqHXpaSh4AN;uid=anthropic/claude-3.5-sonnet;registry=openrouter;proto=openrouter;nativeId=anthropic/claude-3.5-sonnet',
    historyTtlSeconds: 900,
  },
});
await registryTool._call({
  operation: 'chat.sendMessage',
  payload: {
    sessionId: JSON.parse(session).result.sessionId,
    message: 'Hello from the Hedera Agent Kit plugin!',
  },
});
```

For encrypted chat flows, call `chat.start`, `chat.createEncryptedSession`, or `chat.acceptEncryptedSession`. The plugin returns a `handleId`; subsequent `conversation.send`, `conversation.decryptHistoryEntry`, and `conversation.release` operations reuse that state without exposing the raw `ChatConversationHandle`.

## Plugin Development

Create custom plugins by extending the base plugin interface:

```typescript
import { BasePlugin } from '@hashgraphonline/standards-agent-kit';

export class MyCustomPlugin extends BasePlugin {
  name = 'my-custom-plugin';
  
  async initialize(context) {
    // Initialize your plugin
  }
  
  getTools() {
    // Return your custom tools
  }
}
```

## Contributing

Please read our [Contributing Guide](CONTRIBUTING.md) before contributing to this project.

## Resources

- [Standards Agent Kit Documentation](https://hashgraphonline.com/docs/libraries/standards-agent-kit/)
- [HCS Standards Documentation](https://hashgraphonline.com/docs/standards)
- [Hedera Documentation](https://docs.hedera.com)
- [GitHub Repository](https://github.com/hashgraph-online/standards-agent-kit)

## License

Apache-2.0