node-red-contrib-ai-agent 0.1.0 → 0.3.0

package/README.md

@@ -23,6 +23,7 @@ Your feedback and contributions are highly appreciated!
   - **In-Memory**: Store conversation context in memory (volatile)
   - **File-based**: Persist conversation context to disk
 - **AI Model Node**: Configure AI models and API settings
+- **AI Orchestrator Node**: Coordinate multiple agents and create autonomous plans
 - **Tool Integration**: Extend functionality with custom tools
 - **Stateless Design**: Memory nodes are stateless, making them more reliable and scalable
 - **Context Management**: Automatic conversation history management with configurable retention
@@ -89,6 +90,21 @@ Configures the AI model and API settings.
 - **API Key**: Your OpenRouter API key
 - **Name**: Display name for the node
 
+### AI Orchestrator
+Coordinates multiple AI agents by creating and executing plans. It uses an autonomy loop (observe-think-act-reflect) to achieve complex goals.
+
+**Key Features:**
+- **Non-linear Planning**: Supports task dependencies (tasks wait for their predecessors).
+- **Task Prioritization**: Executes higher priority tasks first within dependency constraints.
+- **Dynamic Plan Revision**: Refines the plan based on task outcomes and agent feedback.
+- **Error Recovery**: Automatically handles task failures with recovery strategies (retry, pivot, or fail).
+
+**Properties:**
+- **Max Iterations**: Maximum cycles for the autonomy loop
+- **Planning Strategy**: Simple (linear) or Advanced (dependency-aware)
+- **Default Goal**: Optional fallback goal
+- **Name**: Display name for the node
+
 ### AI Tool Function
 Creates a JavaScript function tool that can be used by the AI Agent.
 
@@ -159,6 +175,18 @@ For more complex scenarios, you can chain multiple agents to process messages in
 
 Each agent will maintain its own conversation context based on its memory configuration.
 
+## Example: Autonomous Orchestration
+
+The AI Orchestrator can manage complex, multi-step tasks:
+
+1. Add an **AI Orchestrator** node
+2. Connect its first output to an **AI Agent**
+3. Connect the agent's output back to the **AI Orchestrator** input
+4. Connect the orchestrator's second output to a **Debug** node
+5. Configure the orchestrator with a goal (e.g., "Write a blog post and then translate it to Spanish")
+
+The orchestrator will create a plan (optionally with dependencies and priorities), dispatch the first available task to the agent, reflect on the result, and then dispatch the next task until completion. If a task fails, it can revise the plan to recover.
+
 ## Best Practices
 
 ### Memory Management

package/orchestrator/orchestrator.html

@@ -0,0 +1,82 @@
+<script type="text/javascript">
+    RED.nodes.registerType('ai-orchestrator', {
+        category: 'ai agent',
+        color: '#E2D96E',
+        defaults: {
+            name: { value: "" },
+            maxIterations: { value: 5, validate: RED.validators.number() },
+            planningStrategy: { value: "simple" },
+            defaultGoal: { value: "" }
+        },
+        inputs: 1,
+        outputs: 2,
+        outputLabels: ["Task Dispatch", "Final Result"],
+        icon: "font-awesome/fa-sitemap",
+        label: function () {
+            return this.name || "ai orchestrator";
+        },
+        paletteLabel: "ai orchestrator"
+    });
+</script>
+
+<script type="text/html" data-template-name="ai-orchestrator">
+    <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="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-maxIterations"><i class="fa fa-repeat"></i> Max Iterations</label>
+        <input type="number" id="node-input-maxIterations" placeholder="5">
+    </div>
+    <div class="form-row">
+        <label for="node-input-planningStrategy"><i class="fa fa-cog"></i> Planning Strategy</label>
+        <select id="node-input-planningStrategy">
+            <option value="simple">Simple (Linear)</option>
+            <option value="advanced">Advanced (LLM-optimized)</option>
+        </select>
+    </div>
+    <div class="form-row">
+        <label for="node-input-defaultGoal"><i class="fa fa-bullseye"></i> Default Goal</label>
+        <textarea id="node-input-defaultGoal" style="width: 100%" rows="3" placeholder="Optional default goal for the orchestrator"></textarea>
+    </div>
+</script>
+
+<script type="text/html" data-content-help-name="ai-orchestrator">
+    <p>The AI Orchestrator node manages complex tasks by decomposing them into a plan and dispatching individual tasks to other AI agents.</p>
+    
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">string | object</span></dt>
+        <dd>The goal or task description if starting a new plan.</dd>
+        <dt>orchestration <span class="property-type">object</span></dt>
+        <dd>The internal state of the orchestration loop (passed back from agents).</dd>
+        <dt>aiagent <span class="property-type">object</span></dt>
+        <dd>The AI model configuration (required for planning and reflection).</dd>
+    </dl>
+
+    <h3>Outputs</h3>
+    <ol class="node-ports">
+        <li>Task Dispatch
+            <dl class="message-properties">
+                <dt>msg.payload <span class="property-type">string</span></dt>
+                <dd>The instruction for the next task.</dd>
+            </dl>
+        </li>
+        <li>Final Result
+            <dl class="message-properties">
+                 <dt>msg.orchestration <span class="property-type">object</span></dt>
+                 <dd>The full orchestration history and final result status.</dd>
+            </dl>
+        </li>
+    </ol>
+
+    <h3>Details</h3>
+    <p>Connect this node to one or more AI agents. The first output should flow into an agent, and the agent's output should loop back to this node's input.</p>
+    <p>The orchestrator supports advanced planning features in "Advanced" mode:</p>
+    <ul>
+        <li><strong>Dependencies:</strong> Tasks can wait for other tasks to complete (<code>dependsOn</code> array).</li>
+        <li><strong>Priorities:</strong> Tasks with higher <code>priority</code> numbers are executed first.</li>
+        <li><strong>Error Recovery:</strong> If a task fails, the orchestrator reflects on the error and can revise the plan to retry or try an alternative approach.</li>
+    </ul>
+    <p>When the goal is achieved or max iterations are reached, the final message is sent to the second output.</p>
+</script>

package/orchestrator/orchestrator.js

@@ -0,0 +1,229 @@
+const axios = require('axios');
+
+module.exports = function (RED) {
+    function AiOrchestratorNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        this.name = config.name || 'AI Orchestrator';
+        this.maxIterations = parseInt(config.maxIterations) || 5;
+        this.planningStrategy = config.planningStrategy || 'simple';
+        this.defaultGoal = config.defaultGoal || '';
+
+        node.on('input', async function (msg, send, done) {
+            send = send || function () { node.send.apply(node, arguments) };
+            node.status({ fill: 'blue', shape: 'dot', text: 'thinking...' });
+
+            try {
+                // Initialize orchestration state if not present
+                if (!msg.orchestration) {
+                    msg.orchestration = {
+                        planId: 'plan-' + Date.now(),
+                        iterations: 0,
+                        goal: msg.payload || node.defaultGoal,
+                        status: 'planning',
+                        history: [],
+                        plan: null
+                    };
+                } else {
+                    msg.orchestration.iterations++;
+                }
+
+                // Check for max iterations
+                if (msg.orchestration.iterations >= node.maxIterations) {
+                    node.warn('Max iterations reached');
+                    msg.orchestration.status = 'failed';
+                    msg.orchestration.error = 'Max iterations reached';
+                    node.status({ fill: 'red', shape: 'dot', text: 'max iterations' });
+                    send([null, msg]); // Output 2 for final result
+                    if (done) done();
+                    return;
+                }
+
+                // AI Configuration check
+                if (!msg.aiagent || !msg.aiagent.apiKey) {
+                    throw new Error('AI Model configuration missing or API key not found.');
+                }
+
+                // Logic based on current status
+                if (msg.orchestration.status === 'planning' || !msg.orchestration.plan) {
+                    await createInitialPlan(node, msg);
+                } else if (msg.orchestration.currentTaskId) {
+                    await reflectAndRefine(node, msg);
+                }
+
+                // Dispatch or Finalize
+                if (msg.orchestration.status === 'completed' || msg.orchestration.status === 'failed') {
+                    node.status({ fill: 'green', shape: 'dot', text: msg.orchestration.status });
+                    send([null, msg]); // Output 2
+                } else {
+                    const nextTask = getNextTask(msg.orchestration.plan);
+                    if (nextTask) {
+                        msg.payload = nextTask.input;
+                        msg.topic = nextTask.type;
+                        msg.orchestration.currentTaskId = nextTask.id;
+                        node.status({ fill: 'blue', shape: 'ring', text: `dispatching: ${nextTask.id}` });
+                        send([msg, null]); // Output 1
+                    } else {
+                        msg.orchestration.status = 'completed';
+                        node.status({ fill: 'green', shape: 'dot', text: 'completed' });
+                        send([null, msg]); // Output 2
+                    }
+                }
+
+                if (done) done();
+            } catch (error) {
+                node.status({ fill: 'red', shape: 'ring', text: 'error' });
+                node.error(error.message, msg);
+                if (done) done(error);
+            }
+        });
+    }
+
+    async function createInitialPlan(node, msg) {
+        const goal = msg.orchestration.goal;
+        const strategy = node.planningStrategy;
+
+        let prompt = `Goal: ${goal}\n\nDecompose this goal into a series of tasks for AI agents. 
+Return a JSON object with a "tasks" array. Each task should have:
+- "id": a short string id (e.g., "t1", "t2")
+- "type": the type of task (e.g., "research", "code", "review")
+- "input": detailed instruction for the agent
+- "status": "pending"
+- "priority": a number (1-10, default 5)
+- "dependsOn": an array of IDs of tasks that must be completed BEFORE this task can start (empty array if none)`;
+
+        if (strategy === 'advanced') {
+            prompt += `\n\nThink about parallel execution. Group related tasks and identify bottlenecks. Ensure dependencies are logical.`;
+        }
+
+        prompt += `\n\nExample:
+{
+  "tasks": [
+    {"id": "t1", "type": "research", "input": "...", "status": "pending", "priority": 10, "dependsOn": []},
+    {"id": "t2", "type": "implementation", "input": "...", "status": "pending", "priority": 5, "dependsOn": ["t1"]}
+  ]
+}`;
+
+        try {
+            const response = await callAI(msg.aiagent, prompt, "You are an AI Orchestrator that creates non-linear plans with dependencies.");
+            const planData = JSON.parse(extractJson(response));
+            msg.orchestration.plan = planData;
+            msg.orchestration.status = 'executing';
+        } catch (error) {
+            throw new Error(`Planning failed: ${error.message}`);
+        }
+    }
+
+    async function reflectAndRefine(node, msg) {
+        const currentTaskId = msg.orchestration.currentTaskId;
+        const taskResult = msg.payload;
+        const isError = msg.error ? true : false;
+
+        // Update history
+        msg.orchestration.history.push({
+            taskId: currentTaskId,
+            result: taskResult,
+            error: msg.error,
+            timestamp: new Date().toISOString()
+        });
+
+        // Update task status in plan
+        const task = msg.orchestration.plan.tasks.find(t => t.id === currentTaskId);
+        if (task) {
+            if (isError) {
+                task.status = 'failed';
+                task.error = msg.error;
+            } else {
+                task.status = 'completed';
+                task.output = taskResult;
+            }
+        }
+
+        const prompt = `Current Goal: ${msg.orchestration.goal}
+Current Plan: ${JSON.stringify(msg.orchestration.plan)}
+Last Task ID: ${currentTaskId}
+Last Task ${isError ? 'Error' : 'Result'}: ${JSON.stringify(isError ? msg.error : taskResult)}
+
+Evaluate the progress. 
+1. If the last task failed, propose a recovery strategy (retry, alternative task, or fail the goal).
+2. If the goal is achieved, set status to "completed".
+3. Otherwise, continue execution. You may refine the plan by adding, removing, or modifying tasks.
+
+Return a JSON object:
+{
+  "analysis": "detailed evaluation of progress and next steps",
+  "status": "executing" | "completed" | "failed",
+  "updatedPlan": { "tasks": [...] }
+}`;
+
+        try {
+            const response = await callAI(msg.aiagent, prompt, "You are an AI Orchestrator that reflects on progress and manages plan revisions.");
+            const reflection = JSON.parse(extractJson(response));
+
+            msg.orchestration.status = reflection.status;
+            if (reflection.updatedPlan) {
+                msg.orchestration.plan = reflection.updatedPlan;
+            }
+        } catch (error) {
+            node.warn(`Reflection failed, continuing with current plan state: ${error.message}`);
+            // Fallback: stay in executing status if it was executing, let getNextTask decide
+        }
+    }
+
+    function getNextTask(plan) {
+        if (!plan || !plan.tasks) return null;
+
+        // Find tasks that are pending AND all their dependencies are completed
+        const eligibleTasks = plan.tasks.filter(t => {
+            if (t.status !== 'pending') return false;
+
+            if (!t.dependsOn || t.dependsOn.length === 0) return true;
+
+            return t.dependsOn.every(depId => {
+                const depTask = plan.tasks.find(pt => pt.id === depId);
+                return depTask && depTask.status === 'completed';
+            });
+        });
+
+        if (eligibleTasks.length === 0) return null;
+
+        // Sort by priority (descending) then by ID
+        eligibleTasks.sort((a, b) => {
+            const priorityA = a.priority || 5;
+            const priorityB = b.priority || 5;
+            if (priorityB !== priorityA) return priorityB - priorityA;
+            return a.id.localeCompare(b.id);
+        });
+
+        return eligibleTasks[0];
+    }
+
+    async function callAI(aiConfig, prompt, systemPrompt) {
+        const response = await axios.post(
+            'https://openrouter.ai/api/v1/chat/completions',
+            {
+                model: aiConfig.model,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: prompt }
+                ],
+                response_format: { type: 'json_object' }
+            },
+            {
+                headers: {
+                    'Authorization': `Bearer ${aiConfig.apiKey}`,
+                    'Content-Type': 'application/json'
+                }
+            }
+        );
+        return response.data.choices[0]?.message?.content || '';
+    }
+
+    function extractJson(text) {
+        const match = text.match(/\{[\s\S]*\}/);
+        return match ? match[0] : text;
+    }
+
+    RED.nodes.registerType('ai-orchestrator', AiOrchestratorNode);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-red-contrib-ai-agent",
-    "version": "0.1.0",
+    "version": "0.3.0",
     "description": "AI Agent for Node-RED",
     "repository": {
         "type": "git",
@@ -32,7 +32,8 @@
         "tool-function/*",
         "tool-http/*",
         "memory-file/*",
-        "memory-inmem/*"
+        "memory-inmem/*",
+        "orchestrator/*"
     ],
     "dependencies": {
         "axios": "^1.6.0",
@@ -60,7 +61,8 @@
             "ai-tool-function": "./tool-function/ai-tool-function.js",
             "ai-tool-http": "./tool-http/ai-tool-http.js",
             "ai-memory-file": "./memory-file/memory-file.js",
-            "ai-memory-inmem": "./memory-inmem/memory-inmem.js"
+            "ai-memory-inmem": "./memory-inmem/memory-inmem.js",
+            "ai-orchestrator": "./orchestrator/orchestrator.js"
         }
     }
 }