plugin-agent-orchestrator 1.0.15 → 1.0.17

package/README.md

@@ -7,6 +7,7 @@ Hierarchical Multi-Agent orchestration for NocoBase AI Employees. Enables Leader
 - **Hierarchical Delegation**: Allows AI Leader agents to break down complex tasks and assign them to specialized sub-agents.
 - **Seamless Integration**: Plugs directly into the existing AI Employee framework.
 - **Execution Tracking**: Monitor sub-agent task execution and responses within the main chat interface.
+- **External RAG Search**: Exposes `external_rag_search` so leaders and sub-agents can retrieve context from NocoBase knowledge bases, including external RAG services.
 
 ## Usage
 1. Enable the plugin in the NocoBase Plugin Manager.
@@ -14,3 +15,98 @@ Hierarchical Multi-Agent orchestration for NocoBase AI Employees. Enables Leader
 3. Configure a primary "Leader" agent.
 4. Add available "Sub-Agents" as tools or skills to the Leader agent.
 5. Interact with the Leader agent; it will automatically delegate tasks when necessary.
+
+## External RAG / Embedding service
+
+Recommended approach: keep source ownership in NocoBase and move chunking, embedding, vector storage, and retrieval to an external lightweight RAG service. This plugin should not own vector infrastructure directly. It delegates search to `plugin-knowledge-base`, which already supports knowledge bases of type `EXTERNAL_RAG`.
+
+### Architecture
+
+1. NocoBase stores the source metadata:
+   - uploaded file attachment id, filename, storage id, URL, owner/role access, or
+   - datasource/collection/record id for database-backed knowledge.
+2. The external RAG service owns:
+   - document fetching or receiving source payloads,
+   - parsing/chunking,
+   - embedding,
+   - vector index,
+   - retrieval.
+3. NocoBase creates a knowledge base with `type = EXTERNAL_RAG` and `options` such as:
+   - `ragProvider: "external-http"`
+   - `ragApiUrl: "https://rag.example.com/search"`
+   - `ragApiKey`
+   - `ragNamespace`
+   - `ragTopK`
+   - `ragScoreThreshold`
+4. Agents use the `external_rag_search` tool. The tool calls `plugin-knowledge-base.searchKnowledgeBases()`, so access control and mixed local/external search remain centralized.
+
+### External search contract
+
+The built-in `external-http` strategy expects:
+
+```http
+POST /search
+Authorization: Bearer <ragApiKey>
+Content-Type: application/json
+```
+
+```json
+{
+  "query": "search text",
+  "topK": 5,
+  "scoreThreshold": 0.3,
+  "namespace": "optional-kb-namespace",
+  "filter": {}
+}
+```
+
+Response:
+
+```json
+{
+  "results": [
+    {
+      "id": "chunk-or-source-id",
+      "content": "matched text",
+      "score": 0.82,
+      "metadata": {
+        "fileId": "123",
+        "filename": "contract.pdf",
+        "collection": "orders",
+        "recordId": "456",
+        "sourceUrl": "/api/attachments/123:download"
+      }
+    }
+  ]
+}
+```
+
+The important rule is that every result should return enough metadata for NocoBase to resolve the original source: `fileId`/`filename` for files, or `collection`/`recordId` for datasource records.
+
+### Lightweight open-source service target
+
+For a small but useful deployment, use a standalone service with:
+
+- Qdrant or LanceDB for vector search.
+- FastAPI or Express for `/ingest`, `/delete`, and `/search`.
+- A small embedding model such as `BAAI/bge-small-en-v1.5`, `intfloat/multilingual-e5-small`, or another model matching the deployment language.
+- A namespace per NocoBase knowledge base.
+
+Minimum API surface:
+
+- `POST /ingest`: receive `{ namespace, source, content | fileUrl | storageRef, metadata }`.
+- `POST /delete`: receive `{ namespace, sourceId }`.
+- `POST /search`: implement the contract above.
+
+For NocoBase datasource knowledge, send each record as a source document with metadata `{ collection, recordId, fields, updatedAt }`; the RAG service chunks and embeds the selected text fields, then returns `collection` and `recordId` in search results.
+
+### E5/OpenAI-compatible embedding
+
+If the external RAG service uses an E5 family model behind an OpenAI-compatible `/v1/embeddings` API, configure the NocoBase knowledge base with `ragProvider: "e5-http"`. `plugin-knowledge-base` will read the selected embedding LLM service and forward its `baseURL`, `apiKey`, and model to the RAG service.
+
+- embed user queries as `query: <question>`;
+- embed document chunks as `passage: <chunk>`;
+- use the same model for ingest and search;
+- recreate the vector collection when changing models or vector dimensions.
+
+The RAG service still owns chunking, embedding calls, vector storage, and metadata mapping. NocoBase owns the LLM service configuration and search authorization path.

package/dist/externalVersion.js

@@ -9,14 +9,14 @@
 
 module.exports = {
   "react": "18.2.0",
-  "@nocobase/client": "2.0.49",
+  "@nocobase/client": "2.0.55",
   "antd": "5.24.2",
   "@ant-design/icons": "5.6.1",
-  "@nocobase/server": "2.0.49",
-  "@nocobase/database": "2.0.49",
-  "@nocobase/actions": "2.0.49",
+  "@nocobase/server": "2.0.55",
+  "@nocobase/database": "2.0.55",
+  "@nocobase/actions": "2.0.55",
   "@langchain/langgraph": "0.2.74",
   "@langchain/core": "0.3.80",
-  "@nocobase/plugin-ai": "2.0.49",
-  "@nocobase/ai": "2.0.49"
+  "@nocobase/plugin-ai": "2.0.55",
+  "@nocobase/ai": "2.0.55"
 };

package/dist/server/plugin.js

@@ -43,6 +43,7 @@ module.exports = __toCommonJS(plugin_exports);
 var import_server = require("@nocobase/server");
 var import_path = __toESM(require("path"));
 var import_delegate_task = require("./tools/delegate-task");
+var import_external_rag_search = require("./tools/external-rag-search");
 var import_tracing = require("./resources/tracing");
 var import_plugin = __toESM(require("./skill-hub/plugin"));
 class PluginAgentOrchestratorServer extends import_server.Plugin {
@@ -62,9 +63,18 @@ class PluginAgentOrchestratorServer extends import_server.Plugin {
     await this.skillHub.load();
     this.app.acl.registerSnippet({
       name: `pm.${this.name}`,
-      actions: ["orchestratorConfig:*", "orchestratorTracing:*", "agentExecutionSpans:*", "skillDefinitions:*", "skillExecutions:*", "skillHub:*", "skillWorkerConfigs:*"]
+      actions: [
+        "orchestratorConfig:*",
+        "orchestratorTracing:*",
+        "agentExecutionSpans:*",
+        "skillDefinitions:*",
+        "skillExecutions:*",
+        "skillHub:*",
+        "skillWorkerConfigs:*"
+      ]
     });
     const toolsManager = this.app.aiManager.toolsManager;
+    toolsManager.registerTools((0, import_external_rag_search.createExternalRagSearchTool)(this));
     toolsManager.registerDynamicTools((0, import_delegate_task.createDelegateToolsProvider)(this));
     (0, import_tracing.registerTracingResource)(this);
     this.app.cronJobManager.addJob({

package/dist/server/services/SkillManager.js

@@ -347,45 +347,6 @@ if table_data_raw and table_data_raw != '{{' + 'tableData}}':
 doc.build(story)
 print('Generated: report.pdf')
 `;
-const SEED_PPTX = `import os, json
-from pptx import Presentation
-from pptx.util import Inches, Pt
-from pptx.enum.text import PP_ALIGN
-
-title = json.loads('''{{title}}''') if '{{title}}'.startswith('"') else '{{title}}'
-subtitle_raw = '''{{subtitle}}'''
-subtitle = json.loads(subtitle_raw) if subtitle_raw.startswith('"') else subtitle_raw if subtitle_raw != '{{' + 'subtitle}}' else ''
-slides_data = json.loads('''{{slides}}''')
-
-prs = Presentation()
-prs.slide_width = Inches(13.333)
-prs.slide_height = Inches(7.5)
-
-# Title slide
-slide = prs.slides.add_slide(prs.slide_layouts[0])
-slide.shapes.title.text = title
-if subtitle and slide.placeholders[1]:
-    slide.placeholders[1].text = subtitle
-
-# Content slides
-for s in slides_data:
-    slide = prs.slides.add_slide(prs.slide_layouts[1])
-    slide.shapes.title.text = s.get('title', '')
-    body = slide.placeholders[1].text_frame
-    body.clear()
-    for i, bullet in enumerate(s.get('bullets', [])):
-        if i == 0:
-            body.paragraphs[0].text = bullet
-        else:
-            p = body.add_paragraph()
-            p.text = bullet
-        body.paragraphs[-1].font.size = Pt(18)
-
-output_dir = os.environ.get('OUTPUT_DIR', '/output')
-filepath = os.path.join(output_dir, 'presentation.pptx')
-prs.save(filepath)
-print('Generated: presentation.pptx')
-`;
 const SEED_CHART = `import os, json
 import matplotlib
 matplotlib.use('Agg')

package/dist/server/skill-hub/plugin.js

@@ -498,7 +498,7 @@ IMPORTANT: This skill requires human confirmation. Pass best-effort args; the us
                   filter: { id: skill.get("id"), enabled: true }
                 });
                 if (!latestSkill) {
-                  return { error: `Skill "${skill.get("name")}" is no longer available` };
+                  return { status: "error", content: `Skill "${skill.get("name")}" is no longer available` };
                 }
                 const result = await this.executeSkill(latestSkill, args, toolCtx);
                 return {
@@ -530,7 +530,7 @@ IMPORTANT: This skill requires human confirmation. Pass best-effort args; the us
           const cutoff = new Date(Date.now() - MAX_AGE_MS);
           const repo = this.db.getRepository("skillExecutions");
           const outdated = await repo.find({
-            where: { createdAt: { $lt: cutoff } }
+            filter: { createdAt: { $lt: cutoff } }
           });
           if (outdated.length > 0) {
             for (const record of outdated) {
@@ -579,7 +579,7 @@ IMPORTANT: This skill requires human confirmation. Pass best-effort args; the us
       const hours = config ? config.get("retentionHours") : 24;
       if (hours > 0) {
         const cutoff = new Date(Date.now() - hours * 60 * 60 * 1e3);
-        const results = await repo.find({ where: { createdAt: { $lt: cutoff } }, fields: ["id"] });
+        const results = await repo.find({ filter: { createdAt: { $lt: cutoff } }, fields: ["id"] });
         for (const rec of results) {
           await rec.destroy();
         }

package/dist/server/tools/delegate-task.js

@@ -37,6 +37,7 @@ var import_tools = require("@langchain/core/tools");
 var import_messages = require("@langchain/core/messages");
 var import_ExecutionSpanService = require("../services/ExecutionSpanService");
 const ORCHESTRATOR_DEPTH_KEY = "__orchestratorDepth";
+const ORCHESTRATOR_PATH_KEY = "__orchestratorPath";
 const MAX_DISPATCH_CONCURRENCY = 5;
 const MAX_DISPATCH_TASKS = 20;
 const MAX_TOOL_NAME_LENGTH = 64;
@@ -554,7 +555,7 @@ function invalidateDelegateToolsCache() {
   registeredDelegateNamesByPlugin = /* @__PURE__ */ new WeakMap();
 }
 async function invokeDelegateTask(ctx, plugin, options) {
-  var _a, _b, _c, _d, _e;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
   const {
     leaderUsername,
     subAgentUsername,
@@ -573,6 +574,27 @@ async function invokeDelegateTask(ctx, plugin, options) {
   } = options;
   const ctxSnapshot = captureCtxSnapshot(ctx);
   const currentDepth = ctx[ORCHESTRATOR_DEPTH_KEY] ?? 0;
+  const currentPath = ctx[ORCHESTRATOR_PATH_KEY] ?? [leaderUsername];
+  if (currentPath.includes(subAgentUsername)) {
+    const loopChain = [...currentPath, subAgentUsername].join(" -> ");
+    await logDelegation(ctx, plugin, {
+      leaderUsername,
+      subAgentUsername,
+      toolName,
+      task,
+      context,
+      result: "",
+      status: "error",
+      depth: currentDepth,
+      durationMs: 0,
+      error: `Circular delegation detected: ${loopChain}.`,
+      snapshot: ctxSnapshot
+    });
+    return {
+      status: "error",
+      content: `Circular delegation detected: ${loopChain}. Execution aborted to prevent infinite reasoning loops.`
+    };
+  }
   if (currentDepth >= maxDepth) {
     await logDelegation(ctx, plugin, {
       leaderUsername,
@@ -677,7 +699,7 @@ async function invokeDelegateTask(ctx, plugin, options) {
       const entryName = toolEntry.definition.name;
       if (!entryName) continue;
       const employeeSkill = employeeSkillMap.get(entryName);
-      if (!employeeSkill || isDelegateToolName(plugin, entryName) || employeeSkill.autoCall !== true || toolEntry.defaultPermission !== "ALLOW") {
+      if (!employeeSkill || isDelegateToolName(plugin, entryName) || employeeSkill.autoCall !== true) {
         continue;
       }
       langchainTools.push(
@@ -689,6 +711,12 @@ async function invokeDelegateTask(ctx, plugin, options) {
             var _a2;
             const invokeCtx = Object.create(ctx);
             invokeCtx[ORCHESTRATOR_DEPTH_KEY] = currentDepth + 1;
+            invokeCtx[ORCHESTRATOR_PATH_KEY] = [...currentPath, subAgentUsername];
+            invokeCtx._currentAIEmployee = subAgentUsername;
+            if (ctx.state) {
+              invokeCtx.state = Object.create(ctx.state);
+              invokeCtx.state.currentAIEmployee = subAgentUsername;
+            }
             const toolStartedAt = Date.now();
             const isSkillHubTool = entryName === "skill_hub_execute" || entryName.startsWith("skill_hub_");
             const toolSpan = await spanService.create({
@@ -771,7 +799,27 @@ async function invokeDelegateTask(ctx, plugin, options) {
       llm: chatModel,
       tools: langchainTools
     });
-    const systemPrompt = ((_e = subAgentEmployee.chatSettings) == null ? void 0 : _e.systemPrompt) || subAgentEmployee.bio || `You are an AI assistant named "${subAgentEmployee.nickname || subAgentUsername}". ${subAgentEmployee.about || ""}`;
+    let systemPrompt = ((_e = subAgentEmployee.chatSettings) == null ? void 0 : _e.systemPrompt) || subAgentEmployee.bio || `You are an AI assistant named "${subAgentEmployee.nickname || subAgentUsername}". ${subAgentEmployee.about || ""}`;
+    try {
+      const kbPlugin = ctx.app.pm.get("plugin-knowledge-base");
+      if (kbPlugin == null ? void 0 : kbPlugin.sessionContext) {
+        const sessionId = ((_h = (_g = (_f = ctx.action) == null ? void 0 : _f.params) == null ? void 0 : _g.values) == null ? void 0 : _h.sessionId) || ((_j = (_i = ctx.action) == null ? void 0 : _i.params) == null ? void 0 : _j.sessionId) || ((_k = ctx.state) == null ? void 0 : _k.sessionId);
+        const contextSummary = await kbPlugin.sessionContext.buildSummary(
+          { rootRunId, ...sessionId ? { sessionId } : {} },
+          6e3
+        );
+        if (contextSummary) {
+          systemPrompt += `
+
+<shared_context>
+The following context was shared by other agents in this workflow. Use it to avoid redundant work:
+${contextSummary}
+</shared_context>`;
+        }
+      }
+    } catch (e) {
+      (_m = (_l = ctx.app.log) == null ? void 0 : _l.debug) == null ? void 0 : _m.call(_l, `[AgentOrchestrator] Shared context injection skipped: ${e.message}`);
+    }
     const combinedTask = context ? `Task: ${task}
 
 Context Provided:
@@ -867,9 +915,17 @@ ${context}` : `Task: ${task}`;
         traceCount: trace.length + 1
       }
     });
+    const diagnosticTrace = trace.filter((t) => t.type === "tool_error" || t.type === "error").map((t) => `[${t.toolName ? `Tool: ${t.toolName}` : "Sub-agent"}] Error: ${t.content || t.title}`).join("\n");
+    const formattedError = [
+      `Sub-agent "${subAgentUsername}" failed execution: ${e.message}`,
+      diagnosticTrace ? `
+Diagnostic Details of internal failures:
+${diagnosticTrace}` : "",
+      `Suggestion: Review the tool parameters above or try dividing the task into simpler independent tasks.`
+    ].filter(Boolean).join("\n");
     return {
       status: "error",
-      content: `Sub-agent "${subAgentUsername}" failed: ${e.message}`
+      content: formattedError
     };
   }
 }

package/dist/server/tools/external-rag-search.js

@@ -0,0 +1,140 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var external_rag_search_exports = {};
+__export(external_rag_search_exports, {
+  createExternalRagSearchTool: () => createExternalRagSearchTool
+});
+module.exports = __toCommonJS(external_rag_search_exports);
+var import_zod = require("zod");
+const TOOL_NAME = "external_rag_search";
+const MAX_CONTENT_LENGTH = 4e3;
+function truncate(value, max = MAX_CONTENT_LENGTH) {
+  const text = typeof value === "string" ? value : value == null ? "" : String(value);
+  return text.length > max ? `${text.slice(0, max)}...` : text;
+}
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return String(value);
+    }
+  }
+  return void 0;
+}
+function normalizeResult(result) {
+  const metadata = (result == null ? void 0 : result.metadata) ?? {};
+  const sourceId = firstString(
+    result == null ? void 0 : result.id,
+    metadata.id,
+    metadata.sourceId,
+    metadata.documentId,
+    metadata.docId,
+    metadata.fileId,
+    metadata.recordId
+  );
+  const filename = firstString(metadata.filename, metadata.fileName, metadata.name, metadata.title, metadata.source);
+  return {
+    content: truncate(result == null ? void 0 : result.content),
+    score: Number((result == null ? void 0 : result.rerankScore) ?? (result == null ? void 0 : result.score) ?? (result == null ? void 0 : result.vectorScore) ?? 0),
+    knowledgeBaseId: result == null ? void 0 : result.knowledgeBaseId,
+    knowledgeBaseName: result == null ? void 0 : result.knowledgeBaseName,
+    source: {
+      id: sourceId,
+      filename,
+      url: firstString(metadata.url, metadata.fileUrl, metadata.sourceUrl),
+      collection: firstString(metadata.collection, metadata.collectionName),
+      recordId: firstString(metadata.recordId, metadata.rowId)
+    },
+    metadata
+  };
+}
+function createExternalRagSearchTool(plugin) {
+  return {
+    scope: "CUSTOM",
+    execution: "backend",
+    defaultPermission: "ALLOW",
+    introduction: {
+      title: "External RAG Search",
+      about: "Search NocoBase knowledge bases through plugin-knowledge-base, including EXTERNAL_RAG services that own chunking, embedding, and retrieval."
+    },
+    definition: {
+      name: TOOL_NAME,
+      description: `Search configured knowledge bases for relevant context. Use this before answering questions that require documents, files, or datasource-backed knowledge.
+
+The search may be served by an external RAG service. Results include content plus source identifiers such as id, filename, collection, and recordId when the external service provides them.`,
+      schema: import_zod.z.object({
+        query: import_zod.z.string().min(1).describe("Natural-language search query."),
+        knowledgeBaseIds: import_zod.z.array(import_zod.z.string().min(1)).optional().describe(
+          "Optional list of NocoBase knowledge base IDs to search. If omitted, all accessible KBs are searched."
+        ),
+        topK: import_zod.z.number().int().min(1).max(20).optional().describe("Maximum results to return. Default 5, max 20."),
+        scoreThreshold: import_zod.z.number().min(0).max(1).optional().describe("Minimum relevance score. Default is controlled by plugin-knowledge-base.")
+      })
+    },
+    invoke: async (ctx, args) => {
+      var _a, _b, _c, _d, _e;
+      const query = typeof (args == null ? void 0 : args.query) === "string" ? args.query.trim() : "";
+      if (!query) {
+        return { status: "error", content: "Missing required field: query." };
+      }
+      const kbPlugin = (_c = (_b = (_a = ctx == null ? void 0 : ctx.app) == null ? void 0 : _a.pm) == null ? void 0 : _b.get) == null ? void 0 : _c.call(_b, "plugin-knowledge-base");
+      if (!(kbPlugin == null ? void 0 : kbPlugin.searchKnowledgeBases)) {
+        return {
+          status: "error",
+          content: "plugin-knowledge-base is not installed or does not expose searchKnowledgeBases()."
+        };
+      }
+      try {
+        const results = await kbPlugin.searchKnowledgeBases(ctx, query, {
+          knowledgeBaseIds: Array.isArray(args.knowledgeBaseIds) ? args.knowledgeBaseIds.map(String) : void 0,
+          topK: args.topK,
+          scoreThreshold: args.scoreThreshold,
+          rerank: true
+        });
+        return {
+          status: "success",
+          content: JSON.stringify({
+            query,
+            results: (results ?? []).map(normalizeResult)
+          })
+        };
+      } catch (error) {
+        (_e = (_d = plugin.app.log) == null ? void 0 : _d.error) == null ? void 0 : _e.call(_d, "[AgentOrchestrator] external_rag_search failed", error);
+        return {
+          status: "error",
+          content: `External RAG search failed: ${(error == null ? void 0 : error.message) || String(error)}`
+        };
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createExternalRagSearchTool
+});

package/dist/server/tools/skill-execute.js

@@ -69,9 +69,8 @@ IMPORTANT: If the skill returns file download URLs, you MUST format them as clic
         required: ["action"]
       }
     },
-    async invoke(args, options) {
+    async invoke(ctx, args, _id) {
       var _a;
-      const ctx = options == null ? void 0 : options.context;
       plugin.app.logger.info(`[skill-execute] Tool invoked with action: ${args.action}, skillName: ${args.skillName}`);
       if (args.action === "list") {
         const skills = await plugin.db.getRepository("skillDefinitions").find({

package/package.json

@@ -4,7 +4,7 @@
   "displayName.zh-CN": "代理协调器",
   "displayName.vi-VN": "Điều phối Agent",
   "description": "Hierarchical Multi-Agent orchestration for NocoBase AI Employees. Enables Leader agents to delegate tasks to Sub-Agent employees without modifying core plugin-ai.",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "license": "Apache-2.0",
   "main": "dist/server/index.js",
   "keywords": [
@@ -42,4 +42,4 @@
     "@nocobase/ai": "2.x",
     "@nocobase/plugin-ai": "2.x"
   }
-}
+}