@hashgraphonline/conversational-agent

import { BasePlugin, AbstractSigner, 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 { WebBrowserPlugin } from './plugins/web-browser/WebBrowserPlugin'; import { IStateManager } from '@hashgraphonline/standards-agent-kit'; import { MCPServerConfig, MCPConnectionStatus } from './mcp/types'; import { ContentStoreManager } from './services/content-store-manager'; import { SmartMemoryManager, SmartMemoryConfig } from './memory'; import { FormSubmission } from './forms/types'; export type ToolDescriptor = { name: string; namespace?: string; }; export type ChatHistoryItem = { type: 'human' | 'ai' | 'system'; 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' | 'openrouter'; verbose?: boolean; operationalMode?: AgentOperationalMode; userAccountId?: string; customSystemMessagePreamble?: string; customSystemMessagePostamble?: string; additionalPlugins?: BasePlugin[]; stateManager?: IStateManager; scheduleUserTransactionsInBytesMode?: boolean; mirrorNodeConfig?: MirrorNodeConfig; disableLogging?: boolean; enabledPlugins?: string[]; disabledPlugins?: string[]; toolFilter?: (tool: { name: string; namespace?: string; }) => boolean; mcpServers?: MCPServerConfig[]; walletExecutor?: (base64: string, network: 'mainnet' | 'testnet') => Promise<{ transactionId: string; }>; /** Optional: provide a signer factory to override default signer selection */ customSignerFactory?: (args: { operationalMode: AgentOperationalMode; accountId: string; network: NetworkType; }) => AbstractSigner; /** Enable automatic entity memory functionality (default: true) */ entityMemoryEnabled?: boolean; /** Configuration for entity memory system */ entityMemoryConfig?: SmartMemoryConfig; /** * Provider used for entity extraction/resolution tools (defaults to llmProvider or 'openai') */ entityMemoryProvider?: 'openai' | 'anthropic' | 'openrouter'; /** * Model name for entity extraction/resolution tools (defaults per provider) */ entityMemoryModelName?: string; openRouterApiKey?: string; openRouterBaseURL?: string; } /** * 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 { private static readonly NOT_INITIALIZED_ERROR; protected agent?: AgentInstance; hcs10Plugin: HCS10Plugin; hcs2Plugin: HCS2Plugin; inscribePlugin: InscribePlugin; hbarPlugin: HbarPlugin; webBrowserPlugin: WebBrowserPlugin; 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>; /** * Process form submission through the conversational agent * @param {FormSubmission} submission - The form submission data * @returns {Promise<ChatResponse>} The agent's response after processing the form * @throws {Error} If agent is not initialized or doesn't support form processing */ processFormSubmission(submission: FormSubmission): 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 signer - The 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; /** * 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>; /** * Switch operational mode */ switchMode(mode?: AgentOperationalMode): void; /** * Get usage statistics */ getUsageStats(): unknown; /** * Clear usage statistics */ clearUsageStats(): void; /** * Shutdown the agent */ shutdown(): Promise<void>; private extractResponseText; }