node-red-contrib-ai-agent 0.0.1 → 0.0.3

package/README.md

@@ -1,9 +1,80 @@
-# AI Agent - Module for Node-Red #
-
-## Description ##
-
-This is a "work in progress" AI Agent for Node-RED.
-
-## Snapshot ##
-
-![AI Agent Basic Example](/snapshots/ai-agent.png?raw=true "Basic use")
+# Node-RED AI Agent
+
+> **Note**: This project is currently in **beta** and under active development. It is not yet stable, and many changes are expected. Use in production with caution.
+
+## Overview
+
+A powerful AI Agent for Node-RED that enables natural language processing and tool integration. This node allows you to create AI-powered flows with support for function calling and external tool integration.
+
+## ⚠️ Beta Notice
+
+This project is currently in **beta** and under active development. Please be aware that:
+- Breaking changes may occur between releases
+- Not all features are fully implemented or stable
+- Documentation may be incomplete
+- Performance optimizations are still in progress
+
+Your feedback and contributions are highly appreciated!
+
+## Features
+
+- Integration with OpenRouter's AI models
+- Support for function calling and tool execution
+- Easy configuration through Node-RED's interface
+- Conversation context management
+- Extensible with custom tools
+
+## Getting Started
+
+1. Install the package via the Node-RED palette manager
+2. Add an AI Model node to configure your OpenRouter API key and model
+3. Add AI Tool nodes to define custom functions
+4. Connect to an AI Agent node to process messages
+
+## Example: Today's Joke
+
+Here's an example flow that tells a joke related to today's date using a custom tool:
+
+![Today's Joke Flow](https://raw.githubusercontent.com/lesichkovm/node-red-contrib-ai-agent/refs/heads/main/snapshots/todays-joke-flow.png "Example flow showing the Today's Joke implementation")
+
+### Flow Output
+
+When executed, the flow will generate a joke related to the current date:
+
+![Today's Joke Output](https://raw.githubusercontent.com/lesichkovm/node-red-contrib-ai-agent/refs/heads/main/snapshots/todays-joke.png "Example output showing a date-related joke")
+
+## Basic Usage
+
+1. **AI Model Node**: Configure your AI model and API settings
+2. **AI Tool Node**: Define custom functions and tools
+3. **AI Agent Node**: Process messages with AI and tool integration
+
+## Advanced Features
+
+- **Tool Integration**: Extend functionality with custom tools
+- **Context Management**: Maintain conversation history
+- **Flexible Configuration**: Customize model parameters and behavior
+
+## Contributing
+
+Contributions are welcome! Whether you want to report bugs, suggest features, or submit code changes, please feel free to open an issue or submit a pull request.
+
+### How to Contribute
+1. Report bugs or suggest features by opening an issue
+2. Submit pull requests for bug fixes or new features
+3. Help improve documentation
+4. Test the package and report any issues you find
+
+### Reporting Issues
+When reporting issues, please include:
+- Node-RED version
+- Package version
+- Steps to reproduce the issue
+- Any error messages received
+
+### Development
+To contribute to development:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request

package/agent/ai-agent-icon.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="100" height="100" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+    <defs>
+        <linearGradient id="agentGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+            <stop offset="0%" style="stop-color:#4a90e2;stop-opacity:1" />
+            <stop offset="100%" style="stop-color:#7b68ee;stop-opacity:1" />
+        </linearGradient>
+    </defs>
+    <circle cx="50" cy="50" r="45" fill="url(#agentGradient)" stroke="#3a7bc8" stroke-width="2"/>
+    <path d="M35 40 Q50 25 65 40 M35 60 Q50 75 65 60" stroke="white" stroke-width="5" stroke-linecap="round" fill="none"/>
+</svg>

package/agent/ai-agent.html

@@ -0,0 +1,96 @@
+<script type="text/javascript">
+  RED.nodes.registerType('ai-agent', {
+    category: 'AI Agent',
+    color: '#a6bbcf',
+    defaults: {
+      name: { value: '' },
+      systemPrompt: { 
+        value: 'You are a helpful AI assistant.',
+        required: true
+      },
+      responseType: { 
+        value: 'text', 
+        required: true,
+        validate: function(val) {
+          return ['text', 'object'].includes(val);
+        }
+      }
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: 'agent/ai-agent-icon.svg',
+    label: function() {
+      return this.name || 'AI Agent';
+    },
+    paletteLabel: 'AI Agent',
+    oneditprepare: function() {
+      // Always show OpenRouter help since we only support OpenRouter now
+      $('#openrouter-help').show();
+    }
+  });
+</script>
+
+<!-- START: Template -->
+<script type="text/x-red" data-template-name="ai-agent">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="AI Agent">
+  </div>
+  
+  <div class="form-row">
+    <label for="node-input-systemPrompt"><i class="fa fa-comment"></i> System Prompt</label>
+    <textarea type="text" id="node-input-systemPrompt" placeholder="You are a helpful AI assistant." style="width: 100%; height: 80px; resize: vertical; font-family: monospace;"></textarea>
+  </div>
+  
+  <div class="form-row">
+    <label><i class="fa fa-robot"></i> AI Agent</label>
+    <div class="form-tips" style="width: 70%;">
+      <p>This node uses OpenRouter for AI responses. Connect an <b>AI Model</b> node to configure the model and API key.</p>
+    </div>
+  </div>
+  
+  <div class="form-row">
+    <label for="node-input-responseType"><i class="fa fa-reply"></i> Response Format</label>
+    <select id="node-input-responseType" style="width: 100%;">
+      <option value="text">Text Only</option>
+      <option value="object">Structured Object</option>
+    </select>
+  </div>
+  
+  <div id="openrouter-help" class="form-tips" style="display: none; margin-top: 15px; padding: 10px; background: #f8f9fa; border-radius: 4px; border-left: 3px solid #3b78e7;">
+    <p><i class="fa fa-info-circle"></i> <strong>Note:</strong> When using OpenRouter, connect an AI Model node to provide the model and API key configuration.</p>
+    <p>The AI Model node will add an <code>aiagent</code> property to the message with the required configuration.</p>
+  </div>
+</script>
+<!-- END: Template -->
+
+<!-- START: Help -->
+<script type="text/x-red" data-help-name="ai-agent">
+  <h3>AI Agent Node</h3>
+  <p>An intelligent agent that processes and responds to messages with configurable behavior.</p>
+  
+  <h4>Features</h4>
+  <ul>
+    <li>Multiple agent types (Assistant, Chatbot)</li>
+    <li>Configurable response formats</li>
+    <li>Conversation context tracking</li>
+    <li>Error handling and status reporting</li>
+  </ul>
+  
+  <h4>Usage</h4>
+  <ol>
+    <li>Connect the node to a message source (e.g., HTTP input, inject node)</li>
+    <li>Configure the agent type and response format</li>
+    <li>Process the response in your flow</li>
+  </ol>
+  
+  <h4>Output Formats</h4>
+  <p><b>Text Only:</b> Simple string response</p>
+  <p><b>Structured Object:</b> Detailed response including metadata and context</p>
+  
+  <h4>Examples</h4>
+  <p><b>Input:</b> "Hello"</p>
+  <p><b>Assistant Output:</b> "Hello! How can I assist you today?"</p>
+  <p><b>Chatbot Output:</b> "Hi there! What would you like to chat about?"</p>
+</script>
+<!-- END: Help -->

package/agent/ai-agent.js

@@ -0,0 +1,216 @@
+const axios = require('axios');
+
+module.exports = function (RED) {
+  function AiAgentNode(config) {
+    RED.nodes.createNode(this, config)
+    var node = this
+    
+    // Configuration
+    this.agentName = config.name || 'AI Agent'
+    this.systemPrompt = config.systemPrompt || 'You are a helpful AI assistant.'
+    this.responseType = config.responseType || 'text'
+    
+    // Initialize agent state
+    this.context = {
+      conversation: [],
+      lastInteraction: null
+    }
+    
+    // Default responses
+    this.defaultResponse = 'I understand you said: '
+
+    // Handle node cleanup
+    node.on('close', function (done) {
+      // Clean up any resources here
+      node.status({})
+      if (done) done()
+    })
+
+    // Process incoming messages
+    node.on('input', async function (msg, send, done) {
+      // Set status to processing
+      node.status({ fill: 'blue', shape: 'dot', text: 'processing...' });
+      
+      // Validate AI configuration
+      const validateAIConfig = () => {
+        if (!msg.aiagent || !msg.aiagent.model || !msg.aiagent.apiKey) {
+          const errorMsg = 'Missing required AI configuration. Ensure an AI Model node is properly connected and configured.';
+          node.status({ fill: 'red', shape: 'ring', text: 'Error: Missing AI config' });
+          node.error(errorMsg, msg);
+          throw new Error(errorMsg);
+        }
+      };
+      
+      try {
+        validateAIConfig();
+        
+        // Get input from message or use default
+        const input = msg.payload || {};
+        const inputText = typeof input === 'string' ? input : JSON.stringify(input);
+        
+        // Update conversation context
+        node.context.lastInteraction = new Date();
+        node.context.conversation.push({ 
+          role: 'user', 
+          content: inputText, 
+          timestamp: node.context.lastInteraction 
+        });
+        
+        let response;
+        
+        try {
+          // Use OpenRouter for AI responses
+          response = await generateAIResponse.call(node, inputText, msg.aiagent);
+        } catch (error) {
+          const errorMsg = error.response?.data?.error?.message || error.message;
+          node.status({fill:"red", shape:"ring", text:"API Error: " + (errorMsg || 'Unknown error').substring(0, 30)});
+          node.error('OpenRouter API Error: ' + errorMsg, msg);
+          if (done) done(error);
+          return;
+        }
+        
+        // Update context with AI response
+        node.context.conversation.push({ role: 'assistant', content: response, timestamp: new Date() })
+        
+        // Format response based on configuration
+        if (node.responseType === 'object') {
+          msg.payload = {
+            agent: node.agentName,
+            type: 'ai',
+            input: input,
+            response: response,
+            timestamp: new Date().toISOString(),
+            context: {
+              conversationLength: node.context.conversation.length,
+              lastInteraction: node.context.lastInteraction
+            }
+          }
+        } else {
+          msg.payload = response
+        }
+        
+        // Send the message
+        send(msg)
+        
+        // Update status
+        node.status({ fill: 'green', shape: 'dot', text: 'ready' })
+        
+        // Complete processing
+        if (done) {
+          done()
+        }
+      } catch (error) {
+        // Handle errors
+        const errorMsg = error.message || 'Unknown error occurred'
+        node.status({ fill: 'red', shape: 'ring', text: 'error' })
+        node.error('Error in AI Agent: ' + errorMsg, msg)
+        if (done) {
+          done(error)
+        }
+      }
+    })
+    
+    // Generate AI response using OpenRouter API
+    async function generateAIResponse(input, aiConfig) {
+      const messages = [
+        {
+          role: 'system',
+          content: node.systemPrompt
+        },
+        {
+          role: 'user',
+          content: input
+        }
+      ];
+      
+      node.status({fill:"blue", shape:"dot", text:"Calling " + aiConfig.model + "..."});
+      
+      // Prepare tools array if available
+      const tools = aiConfig.tools ? aiConfig.tools.map(tool => ({
+        type: 'function',
+        function: {
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.parameters || {}
+        }
+      })) : [];
+      
+      // Initial API call
+      const response = await axios.post(
+        'https://openrouter.ai/api/v1/chat/completions',
+        {
+          model: aiConfig.model,
+          messages: messages,
+          temperature: aiConfig.temperature || 0.7,
+          max_tokens: aiConfig.maxTokens || 1000,
+          tools: tools.length > 0 ? tools : undefined,
+          tool_choice: tools.length > 0 ? 'auto' : 'none'
+        },
+        {
+          headers: {
+            'Authorization': `Bearer ${aiConfig.apiKey}`,
+            'Content-Type': 'application/json',
+            'HTTP-Referer': 'https://nodered.org/',
+            'X-Title': 'Node-RED AI Agent'
+          }
+        }
+      );
+      
+      const responseMessage = response.data.choices[0].message;
+      
+      // Check if the model wants to call a tool
+      const toolCalls = responseMessage.tool_calls;
+      if (toolCalls && toolCalls.length > 0) {
+        // Process each tool call
+        for (const toolCall of toolCalls) {
+          const functionName = toolCall.function.name;
+          const functionArgs = JSON.parse(toolCall.function.arguments || '{}');
+          
+          // Find the tool
+          const tool = aiConfig.tools?.find(t => t.name === functionName);
+          if (!tool) {
+            throw new Error(`Tool ${functionName} not found`);
+          }
+          
+          // Execute the tool
+          const toolResponse = await tool.execute(functionArgs);
+          
+          // Add the tool response to the messages
+          messages.push({
+            role: 'tool',
+            content: JSON.stringify(toolResponse),
+            tool_call_id: toolCall.id
+          });
+        }
+        
+        // Make a second request with the tool responses
+        const secondResponse = await axios.post(
+          'https://openrouter.ai/api/v1/chat/completions',
+          {
+            model: aiConfig.model,
+            messages: messages,
+            temperature: aiConfig.temperature || 0.7,
+            max_tokens: aiConfig.maxTokens || 1000,
+            tools: tools,
+            tool_choice: 'none' // Force the model to respond normally
+          },
+          {
+            headers: {
+              'Authorization': `Bearer ${aiConfig.apiKey}`,
+              'Content-Type': 'application/json',
+              'HTTP-Referer': 'https://nodered.org/',
+              'X-Title': 'Node-RED AI Agent'
+            }
+          }
+        );
+        
+        return secondResponse.data.choices[0].message.content.trim();
+      }
+      
+      return responseMessage.content.trim();
+    }
+  }
+
+  // Registering the node-red type
+  RED.nodes.registerType('ai-agent', AiAgentNode)
+}

package/model/ai-model-icon.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="100" height="100" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+    <defs>
+        <linearGradient id="modelGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+            <stop offset="0%" style="stop-color:#32cd32;stop-opacity:1" />
+            <stop offset="100%" style="stop-color:#228b22;stop-opacity:1" />
+        </linearGradient>
+    </defs>
+    <rect x="5" y="25" width="90" height="50" rx="10" fill="url(#modelGradient)" stroke="#1e7a1e" stroke-width="2"/>
+    <circle cx="25" cy="50" r="8" fill="white" opacity="0.8"/>
+</svg>