@hashgraphonline/conversational-agent 0.0.3 → 0.1.1

package/src/langchain-agent.ts

@@ -0,0 +1,333 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { StructuredTool } from '@langchain/core/tools';
+import { createOpenAIToolsAgent, AgentExecutor } from 'langchain/agents';
+import {
+  ChatPromptTemplate,
+  MessagesPlaceholder,
+} from '@langchain/core/prompts';
+import { ChatOpenAI } from '@langchain/openai';
+import {
+  calculateTokenCostSync,
+  getAllHederaCorePlugins,
+  HederaAgentKit,
+  TokenUsageCallbackHandler,
+} from 'hedera-agent-kit';
+import type { TokenUsage, CostCalculation } from 'hedera-agent-kit';
+import {
+  BaseAgent,
+  type ConversationContext,
+  type ChatResponse,
+  type OperationalMode,
+  type UsageStats,
+} from './base-agent';
+import { MCPClientManager } from './mcp/MCPClientManager';
+import { convertMCPToolToLangChain } from './mcp/adapters/langchain';
+
+export class LangChainAgent extends BaseAgent {
+  private executor: AgentExecutor | undefined;
+  private systemMessage = '';
+  private mcpManager?: MCPClientManager;
+
+  async boot(): Promise<void> {
+    if (this.initialized) {
+      this.logger.warn('Agent already initialized');
+      return;
+    }
+
+    try {
+      this.agentKit = await this.createAgentKit();
+      await this.agentKit.initialize();
+
+      const modelName =
+        this.config.ai?.modelName ||
+        process.env.OPENAI_MODEL_NAME ||
+        'gpt-4o-mini';
+      this.tokenTracker = new TokenUsageCallbackHandler(modelName);
+
+      const allTools = this.agentKit.getAggregatedLangChainTools();
+      this.tools = this.filterTools(allTools);
+
+      if (this.config.mcp?.servers && this.config.mcp.servers.length > 0) {
+        await this.initializeMCP();
+      }
+
+      this.systemMessage = this.buildSystemPrompt();
+
+      await this.createExecutor();
+
+      this.initialized = true;
+      this.logger.info('LangChain Hedera agent initialized');
+    } catch (error) {
+      this.logger.error('Failed to initialize agent:', error);
+      throw error;
+    }
+  }
+
+  async chat(
+    message: string,
+    context?: ConversationContext
+  ): Promise<ChatResponse> {
+    if (!this.initialized || !this.executor) {
+      throw new Error('Agent not initialized. Call boot() first.');
+    }
+
+    try {
+      const result = await this.executor.invoke({
+        input: message,
+        chat_history: context?.messages || [],
+      });
+
+      let response: ChatResponse = {
+        output: result.output || '',
+        message: result.output || '',
+        notes: [],
+      };
+
+      const parsedSteps = result?.intermediateSteps?.[0]?.observation;
+      if (
+        parsedSteps &&
+        typeof parsedSteps === 'string' &&
+        this.isJSON(parsedSteps)
+      ) {
+        try {
+          const parsed = JSON.parse(parsedSteps);
+          response = { ...response, ...parsed };
+        } catch (error) {
+          this.logger.error('Error parsing intermediate steps:', error);
+        }
+      }
+
+      if (!response.output || response.output.trim() === '') {
+        response.output = 'Agent action complete.';
+      }
+
+      if (this.tokenTracker) {
+        const tokenUsage = this.tokenTracker.getLatestTokenUsage();
+        if (tokenUsage) {
+          response.tokenUsage = tokenUsage;
+          response.cost = calculateTokenCostSync(tokenUsage);
+        }
+      }
+
+      return response;
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.mcpManager) {
+      await this.mcpManager.disconnectAll();
+    }
+
+    this.executor = undefined;
+    this.agentKit = undefined;
+    this.tools = [];
+    this.initialized = false;
+    this.logger.info('Agent cleaned up');
+  }
+
+  switchMode(mode: OperationalMode): void {
+    if (this.config.execution) {
+      this.config.execution.operationalMode = mode;
+    } else {
+      this.config.execution = { operationalMode: mode };
+    }
+
+    if (this.agentKit) {
+      this.agentKit.operationalMode = mode;
+    }
+
+    this.systemMessage = this.buildSystemPrompt();
+    this.logger.info(`Operational mode switched to: ${mode}`);
+  }
+
+  getUsageStats(): UsageStats {
+    if (!this.tokenTracker) {
+      return {
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+        cost: { totalCost: 0 } as CostCalculation,
+      };
+    }
+
+    const usage = this.tokenTracker.getTotalTokenUsage();
+    const cost = calculateTokenCostSync(usage);
+    return { ...usage, cost };
+  }
+
+  getUsageLog(): UsageStats[] {
+    if (!this.tokenTracker) {
+      return [];
+    }
+
+    return this.tokenTracker.getTokenUsageHistory().map((usage) => ({
+      ...usage,
+      cost: calculateTokenCostSync(usage),
+    }));
+  }
+
+  clearUsageStats(): void {
+    if (this.tokenTracker) {
+      this.tokenTracker.reset();
+      this.logger.info('Usage statistics cleared');
+    }
+  }
+
+  private async createAgentKit(): Promise<HederaAgentKit> {
+    const corePlugins = getAllHederaCorePlugins();
+    const extensionPlugins = this.config.extensions?.plugins || [];
+    const plugins = [...corePlugins, ...extensionPlugins];
+
+    const operationalMode =
+      this.config.execution?.operationalMode || 'returnBytes';
+    const modelName = this.config.ai?.modelName || 'gpt-4o';
+
+    return new HederaAgentKit(
+      this.config.signer,
+      { plugins },
+      operationalMode,
+      this.config.execution?.userAccountId,
+      this.config.execution?.scheduleUserTransactionsInBytesMode ?? true,
+      undefined,
+      modelName,
+      this.config.extensions?.mirrorConfig,
+      this.config.debug?.silent ?? false
+    );
+  }
+
+  private async createExecutor(): Promise<void> {
+    let llm: BaseChatModel;
+    if (this.config.ai?.provider && this.config.ai.provider.getModel) {
+      llm = this.config.ai.provider.getModel() as BaseChatModel;
+    } else if (this.config.ai?.llm) {
+      llm = this.config.ai.llm as BaseChatModel;
+    } else {
+      const apiKey = this.config.ai?.apiKey || process.env.OPENAI_API_KEY;
+      if (!apiKey) {
+        throw new Error('OpenAI API key required');
+      }
+
+      llm = new ChatOpenAI({
+        apiKey,
+        modelName: this.config.ai?.modelName || 'gpt-4o-mini',
+        temperature: this.config.ai?.temperature ?? 0.1,
+        callbacks: this.tokenTracker ? [this.tokenTracker] : [],
+      });
+    }
+
+    const prompt = ChatPromptTemplate.fromMessages([
+      ['system', this.systemMessage],
+      new MessagesPlaceholder('chat_history'),
+      ['human', '{input}'],
+      new MessagesPlaceholder('agent_scratchpad'),
+    ]);
+
+    const langchainTools = this.tools as unknown as StructuredTool[];
+
+    const agent = await createOpenAIToolsAgent({
+      llm,
+      tools: langchainTools,
+      prompt,
+    });
+
+    this.executor = new AgentExecutor({
+      agent,
+      tools: langchainTools,
+      verbose: this.config.debug?.verbose ?? false,
+      returnIntermediateSteps: true,
+    });
+  }
+
+  private handleError(error: unknown): ChatResponse {
+    const errorMessage =
+      error instanceof Error ? error.message : 'Unknown error';
+    this.logger.error('Chat error:', error);
+
+    let tokenUsage: TokenUsage | undefined;
+    let cost: CostCalculation | undefined;
+
+    if (this.tokenTracker) {
+      tokenUsage = this.tokenTracker.getLatestTokenUsage();
+      if (tokenUsage) {
+        cost = calculateTokenCostSync(tokenUsage);
+      }
+    }
+
+    const errorResponse: ChatResponse = {
+      output: 'Sorry, I encountered an error processing your request.',
+      message: 'Error processing request.',
+      error: errorMessage,
+      notes: [],
+    };
+
+    if (tokenUsage) {
+      errorResponse.tokenUsage = tokenUsage;
+    }
+
+    if (cost) {
+      errorResponse.cost = cost;
+    }
+
+    return errorResponse;
+  }
+
+  private async initializeMCP(): Promise<void> {
+    this.mcpManager = new MCPClientManager(this.logger);
+
+    for (const serverConfig of this.config.mcp!.servers!) {
+      if (serverConfig.autoConnect === false) {
+        this.logger.info(
+          `Skipping MCP server ${serverConfig.name} (autoConnect=false)`
+        );
+        continue;
+      }
+
+      const status = await this.mcpManager.connectServer(serverConfig);
+
+      if (status.connected) {
+        this.logger.info(
+          `Connected to MCP server ${status.serverName} with ${status.tools.length} tools`
+        );
+
+        for (const mcpTool of status.tools) {
+          const langchainTool = convertMCPToolToLangChain(
+            mcpTool,
+            this.mcpManager,
+            serverConfig
+          );
+          this.tools.push(langchainTool);
+        }
+      } else {
+        this.logger.error(
+          `Failed to connect to MCP server ${status.serverName}: ${status.error}`
+        );
+      }
+    }
+  }
+
+  /**
+   * Check if a string is valid JSON
+   */
+  private isJSON(str: string): boolean {
+    if (typeof str !== 'string') return false;
+
+    const trimmed = str.trim();
+    if (!trimmed) return false;
+
+    if (
+      !(trimmed.startsWith('{') && trimmed.endsWith('}')) &&
+      !(trimmed.startsWith('[') && trimmed.endsWith(']'))
+    ) {
+      return false;
+    }
+
+    try {
+      JSON.parse(trimmed);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/mcp/MCPClientManager.ts

@@ -0,0 +1,148 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { MCPServerConfig, MCPToolInfo, MCPConnectionStatus } from './types';
+import { Logger } from '@hashgraphonline/standards-sdk';
+
+/**
+ * Manages connections to MCP servers and tool discovery
+ */
+export class MCPClientManager {
+  private clients: Map<string, Client> = new Map();
+  private tools: Map<string, MCPToolInfo[]> = new Map();
+  private logger: Logger;
+
+  constructor(logger: Logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Connect to an MCP server and discover its tools
+   */
+  async connectServer(config: MCPServerConfig): Promise<MCPConnectionStatus> {
+    try {
+      if (this.isServerConnected(config.name)) {
+        return {
+          serverName: config.name,
+          connected: false,
+          error: `Server ${config.name} is already connected`,
+          tools: [],
+        };
+      }
+
+      if (config.transport && config.transport !== 'stdio') {
+        throw new Error(`Transport ${config.transport} not yet supported`);
+      }
+
+      const transport = new StdioClientTransport({
+        command: config.command,
+        args: config.args,
+        ...(config.env && { env: config.env }),
+      });
+
+      const client = new Client({
+        name: `conversational-agent-${config.name}`,
+        version: '1.0.0',
+      }, {
+        capabilities: {},
+      });
+
+      await client.connect(transport);
+      this.clients.set(config.name, client);
+
+      const toolsResponse = await client.listTools();
+      const toolsWithServer: MCPToolInfo[] = toolsResponse.tools.map(tool => ({
+        ...tool,
+        serverName: config.name,
+      }));
+
+      this.tools.set(config.name, toolsWithServer);
+      this.logger.info(`Connected to MCP server ${config.name} with ${toolsWithServer.length} tools`);
+
+      return {
+        serverName: config.name,
+        connected: true,
+        tools: toolsWithServer,
+      };
+    } catch (error) {
+      this.logger.error(`Failed to connect to MCP server ${config.name}:`, error);
+      return {
+        serverName: config.name,
+        connected: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+        tools: [],
+      };
+    }
+  }
+
+  /**
+   * Execute a tool on a specific MCP server
+   */
+  async executeTool(serverName: string, toolName: string, args: Record<string, unknown>): Promise<unknown> {
+    const client = this.clients.get(serverName);
+    if (!client) {
+      throw new Error(`MCP server ${serverName} not connected`);
+    }
+
+    this.logger.debug(`Executing MCP tool ${toolName} on server ${serverName}`, args);
+
+    try {
+      const result = await client.callTool({
+        name: toolName,
+        arguments: args,
+      });
+
+      return result;
+    } catch (error) {
+      this.logger.error(`Error executing MCP tool ${toolName}:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Disconnect all MCP servers
+   */
+  async disconnectAll(): Promise<void> {
+    for (const [name, client] of this.clients) {
+      try {
+        await client.close();
+        this.logger.info(`Disconnected from MCP server ${name}`);
+      } catch (error) {
+        this.logger.error(`Error disconnecting MCP server ${name}:`, error);
+      }
+    }
+    this.clients.clear();
+    this.tools.clear();
+  }
+
+  /**
+   * Get all discovered tools from all connected servers
+   */
+  getAllTools(): MCPToolInfo[] {
+    const allTools: MCPToolInfo[] = [];
+    for (const tools of this.tools.values()) {
+      allTools.push(...tools);
+    }
+    return allTools;
+  }
+
+  /**
+   * Get tools from a specific server
+   */
+  getServerTools(serverName: string): MCPToolInfo[] {
+    return this.tools.get(serverName) || [];
+  }
+
+  /**
+   * Check if a server is connected
+   */
+  isServerConnected(serverName: string): boolean {
+    return this.clients.has(serverName);
+  }
+
+  /**
+   * Get list of connected server names
+   */
+  getConnectedServers(): string[] {
+    return Array.from(this.clients.keys());
+  }
+}

package/src/mcp/adapters/langchain.ts

@@ -0,0 +1,185 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import type { MCPToolInfo, MCPServerConfig } from '../types';
+import type { MCPClientManager } from '../MCPClientManager';
+
+/**
+ * Convert an MCP tool to a LangChain DynamicStructuredTool
+ */
+export function convertMCPToolToLangChain(
+  tool: MCPToolInfo,
+  mcpManager: MCPClientManager,
+  serverConfig?: MCPServerConfig
+): DynamicStructuredTool {
+  const zodSchema = jsonSchemaToZod(tool.inputSchema);
+
+  const sanitizedName = `${tool.serverName}_${tool.name}`.replace(
+    /[^a-zA-Z0-9_]/g,
+    '_'
+  );
+
+  let description = tool.description || `MCP tool ${tool.name} from ${tool.serverName}`;
+  
+  if (serverConfig?.toolDescriptions?.[tool.name]) {
+    description = `${description}\n\n${serverConfig.toolDescriptions[tool.name]}`;
+  }
+  
+  if (serverConfig?.additionalContext) {
+    description = `${description}\n\nContext: ${serverConfig.additionalContext}`;
+  }
+
+  return new DynamicStructuredTool({
+    name: sanitizedName,
+    description,
+    schema: zodSchema,
+    func: async (input) => {
+      try {
+        const result = await mcpManager.executeTool(
+          tool.serverName,
+          tool.name,
+          input
+        );
+
+        if (typeof result === 'string') {
+          return result;
+        } else if (
+          result &&
+          typeof result === 'object' &&
+          'content' in result
+        ) {
+          const content = (result as { content: unknown }).content;
+          if (Array.isArray(content)) {
+            const textParts = content
+              .filter(
+                (item): item is { type: string; text: string } =>
+                  typeof item === 'object' &&
+                  item !== null &&
+                  'type' in item &&
+                  item.type === 'text' &&
+                  'text' in item
+              )
+              .map((item) => item.text);
+            return textParts.join('\n');
+          }
+          return JSON.stringify(content);
+        }
+
+        return JSON.stringify(result);
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : 'Unknown error';
+        return `Error executing MCP tool ${tool.name}: ${errorMessage}`;
+      }
+    },
+  });
+}
+
+/**
+ * Convert JSON Schema to Zod schema
+ * This is a simplified converter that handles common cases
+ */
+function jsonSchemaToZod(schema: unknown): z.ZodTypeAny {
+  if (!schema || typeof schema !== 'object') {
+    return z.object({});
+  }
+
+  const schemaObj = schema as Record<string, unknown>;
+
+  if (schemaObj.type && schemaObj.type !== 'object') {
+    return convertType(schemaObj);
+  }
+
+  if (!schemaObj.properties || typeof schemaObj.properties !== 'object') {
+    return z.object({});
+  }
+
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const [key, value] of Object.entries(schemaObj.properties)) {
+    let zodType = convertType(value);
+
+    const isRequired =
+      Array.isArray(schemaObj.required) && schemaObj.required.includes(key);
+    if (!isRequired) {
+      zodType = zodType.optional();
+    }
+
+    shape[key] = zodType;
+  }
+
+  return z.object(shape);
+}
+
+/**
+ * Convert a single JSON Schema type to Zod
+ */
+function convertType(schema: unknown): z.ZodTypeAny {
+  if (!schema || typeof schema !== 'object' || !('type' in schema)) {
+    return z.unknown();
+  }
+
+  const schemaObj = schema as {
+    type: string;
+    enum?: unknown[];
+    items?: unknown;
+  };
+  let zodType: z.ZodTypeAny;
+
+  switch (schemaObj.type) {
+    case 'string':
+      zodType = z.string();
+      if (schemaObj.enum && Array.isArray(schemaObj.enum)) {
+        zodType = z.enum(schemaObj.enum as [string, ...string[]]);
+      }
+      break;
+
+    case 'number':
+      zodType = z.number();
+      if ('minimum' in schemaObj && typeof schemaObj.minimum === 'number') {
+        zodType = (zodType as z.ZodNumber).min(schemaObj.minimum);
+      }
+      if ('maximum' in schemaObj && typeof schemaObj.maximum === 'number') {
+        zodType = (zodType as z.ZodNumber).max(schemaObj.maximum);
+      }
+      break;
+
+    case 'integer':
+      zodType = z.number().int();
+      if ('minimum' in schemaObj && typeof schemaObj.minimum === 'number') {
+        zodType = (zodType as z.ZodNumber).min(schemaObj.minimum);
+      }
+      if ('maximum' in schemaObj && typeof schemaObj.maximum === 'number') {
+        zodType = (zodType as z.ZodNumber).max(schemaObj.maximum);
+      }
+      break;
+
+    case 'boolean':
+      zodType = z.boolean();
+      break;
+
+    case 'array':
+      if (schemaObj.items) {
+        zodType = z.array(convertType(schemaObj.items));
+      } else {
+        zodType = z.array(z.unknown());
+      }
+      break;
+
+    case 'object':
+      if ('properties' in schemaObj) {
+        zodType = jsonSchemaToZod(schemaObj);
+      } else {
+        zodType = z.object({}).passthrough();
+      }
+      break;
+
+    default:
+      zodType = z.unknown();
+  }
+
+  if ('description' in schemaObj && typeof schemaObj.description === 'string') {
+    zodType = zodType.describe(schemaObj.description);
+  }
+
+  return zodType;
+}