@hashgraphonline/conversational-agent

import { BasePlugin, AgentOperationalMode, MirrorNodeConfig } from 'hedera-agent-kit'; import { Logger, NetworkType } from '@hashgraphonline/standards-sdk'; import { createAgent } from './agent-factory'; import { ChatResponse } from './base-agent'; import { HCS10Plugin } from './plugins/hcs-10/HCS10Plugin'; import { HCS2Plugin } from './plugins/hcs-2/HCS2Plugin'; import { InscribePlugin } from './plugins/inscribe/InscribePlugin'; import { HbarPlugin } from './plugins/hbar/HbarPlugin'; import { IStateManager } from '@hashgraphonline/standards-agent-kit'; import { MCPServerConfig, MCPConnectionStatus } from './mcp/types'; import { ContentStoreManager } from './services/ContentStoreManager'; import { SmartMemoryManager, SmartMemoryConfig } from './memory'; export type ToolDescriptor = { name: string; namespace?: string; }; export type ChatHistoryItem = { type: 'human' | 'ai'; content: string; }; export type AgentInstance = ReturnType<typeof createAgent>; export type MirrorNetwork = 'testnet' | 'mainnet' | 'previewnet'; export interface ConversationalAgentOptions { accountId: string; privateKey: string; network?: NetworkType; openAIApiKey: string; openAIModelName?: string; llmProvider?: 'openai' | 'anthropic'; verbose?: boolean; operationalMode?: AgentOperationalMode; userAccountId?: string; customSystemMessagePreamble?: string; customSystemMessagePostamble?: string; additionalPlugins?: BasePlugin[]; stateManager?: IStateManager; scheduleUserTransactionsInBytesMode?: boolean; mirrorNodeConfig?: MirrorNodeConfig; disableLogging?: boolean; enabledPlugins?: string[]; toolFilter?: (tool: { name: string; namespace?: string; }) => boolean; mcpServers?: MCPServerConfig[]; /** Enable automatic entity memory functionality (default: true) */ entityMemoryEnabled?: boolean; /** Configuration for entity memory system */ entityMemoryConfig?: SmartMemoryConfig; } /** * The ConversationalAgent class is an optional wrapper around the HederaConversationalAgent class, * which includes the OpenConvAIPlugin and the OpenConvaiState by default. * If you want to use a different plugin or state manager, you can pass them in the options. * This class is not required and the plugin can be used directly with the HederaConversationalAgent class. * * @param options - The options for the ConversationalAgent. * @returns A new instance of the ConversationalAgent class. */ export declare class ConversationalAgent { protected agent?: AgentInstance; hcs10Plugin: HCS10Plugin; hcs2Plugin: HCS2Plugin; inscribePlugin: InscribePlugin; hbarPlugin: HbarPlugin; stateManager: IStateManager; private options; logger: Logger; contentStoreManager?: ContentStoreManager; memoryManager?: SmartMemoryManager | undefined; private entityTools?; constructor(options: ConversationalAgentOptions); /** * Initialize the conversational agent with Hedera Hashgraph connection and AI configuration * @throws {Error} If account ID or private key is missing * @throws {Error} If initialization fails */ initialize(): Promise<void>; /** * Get the HCS-10 plugin instance * @returns {HCS10Plugin} The HCS-10 plugin instance */ getPlugin(): HCS10Plugin; /** * Get the state manager instance * @returns {IStateManager} The state manager instance */ getStateManager(): IStateManager; /** * Get the underlying agent instance * @returns {ReturnType<typeof createAgent>} The agent instance * @throws {Error} If agent is not initialized */ getAgent(): ReturnType<typeof createAgent>; /** * Get the conversational agent instance (alias for getAgent) * @returns {ReturnType<typeof createAgent>} The agent instance * @throws {Error} If agent is not initialized */ getConversationalAgent(): ReturnType<typeof createAgent>; /** * Process a message through the conversational agent * @param {string} message - The message to process * @param {Array<{type: 'human' | 'ai'; content: string}>} chatHistory - Previous chat history * @returns {Promise<ChatResponse>} The agent's response * @throws {Error} If agent is not initialized */ processMessage(message: string, chatHistory?: ChatHistoryItem[]): Promise<ChatResponse>; /** * Validates initialization options and throws if required fields are missing. * * @param accountId - The Hedera account ID * @param privateKey - The private key for the account * @throws {Error} If required fields are missing */ private validateOptions; /** * Prepares the list of plugins to use based on configuration. * * @returns Array of plugins to initialize with the agent */ private preparePlugins; /** * Creates the agent configuration object. * * @param serverSigner - The server signer instance * @param llm - The language model instance * @param allPlugins - Array of plugins to use * @returns Configuration object for creating the agent */ private createAgentConfig; /** * Configures the HCS-10 plugin with the state manager. * * @param allPlugins - Array of all plugins */ private configureHCS10Plugin; /** * Create a ConversationalAgent with specific plugins enabled */ private static withPlugins; /** * Create a ConversationalAgent with only HTS (Hedera Token Service) tools enabled */ static withHTS(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with only HCS-2 tools enabled */ static withHCS2(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with only HCS-10 tools enabled */ static withHCS10(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with only inscription tools enabled */ static withInscribe(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with only account management tools enabled */ static withAccount(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with only file service tools enabled */ static withFileService(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with only consensus service tools enabled */ static withConsensusService(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with only smart contract tools enabled */ static withSmartContract(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with all HCS standards plugins */ static withAllStandards(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with minimal Hedera tools (no HCS standards) */ static minimal(options: ConversationalAgentOptions): ConversationalAgent; /** * Create a ConversationalAgent with MCP servers configured */ static withMCP(options: ConversationalAgentOptions, mcpServers: MCPServerConfig[]): ConversationalAgent; /** * Detect the private key type by querying the account info from mirror node * @param {string} accountId - The Hedera account ID * @param {string} privateKey - The private key string * @param {NetworkType} network - The Hedera Hashgraph * @returns {Promise<PrivateKey>} The appropriate PrivateKey instance */ private detectPrivateKeyType; /** * Resolve entity references using LLM-based resolver * @param content - Message content to resolve * @returns Resolved message content with entity IDs replaced */ private resolveEntitiesInMessage; /** * Extract and store entities from agent responses * @param response - Agent response containing potential entity information * @param originalMessage - Original user message for context */ private extractAndStoreEntities; /** * Extract transaction ID from response if available * @param response - Transaction response * @returns Transaction ID or undefined */ private extractTransactionId; /** * Connect to MCP servers asynchronously * @private */ private connectMCP; /** * Get MCP connection status for all servers * @returns {Map<string, MCPConnectionStatus>} Connection status map */ getMCPConnectionStatus(): Map<string, MCPConnectionStatus>; /** * Check if a specific MCP server is connected * @param {string} serverName - Name of the server to check * @returns {boolean} True if connected, false otherwise */ isMCPServerConnected(serverName: string): boolean; /** * Clean up resources */ cleanup(): Promise<void>; private extractResponseText; }