plugin-agent-orchestrator 1.0.32 → 1.0.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,114 +1,114 @@
1
- # plugin-agent-orchestrator
2
-
3
- ## Overview
4
- Hierarchical Multi-Agent orchestration for NocoBase AI Employees. Enables Leader agents to delegate tasks to Sub-Agent employees, with detailed execution tracing and context/memory management.
5
-
6
- ## Features
7
- - **Hierarchical Delegation**: Allows AI Leader agents to break down complex tasks and assign them to specialized sub-agents via native dispatching.
8
- - **Seamless Integration**: Plugs directly into the existing AI Employee framework, capturing execution spans.
9
- - **Execution Tracking**: Monitor sub-agent task execution and nested tool calls in detail within the main chat interface.
10
- - **External RAG Search**: Exposes `external_rag_search` so leaders and sub-agents can retrieve context from NocoBase knowledge bases, including external RAG services.
11
-
12
- ## Usage
13
- 1. Enable the plugin in the NocoBase Plugin Manager.
14
- 2. Navigate to the AI Employee configuration page.
15
- 3. Configure a primary "Leader" agent and specialized "Sub-Agent" employees.
16
- 4. Add the built-in **AI employee task dispatching** (`dispatch-sub-agent-task`) tool to the Leader agent.
17
- 5. Ensure the user role has access to both the Leader and Sub-Agent employees (configured via employee roles mapping).
18
- 6. Interact with the Leader agent; it will automatically delegate tasks to the sub-agents when necessary.
19
-
20
-
21
- ## External RAG / Embedding service
22
-
23
- 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`.
24
-
25
- ### Architecture
26
-
27
- 1. NocoBase stores the source metadata:
28
- - uploaded file attachment id, filename, storage id, URL, owner/role access, or
29
- - datasource/collection/record id for database-backed knowledge.
30
- 2. The external RAG service owns:
31
- - document fetching or receiving source payloads,
32
- - parsing/chunking,
33
- - embedding,
34
- - vector index,
35
- - retrieval.
36
- 3. NocoBase creates a knowledge base with `type = EXTERNAL_RAG` and `options` such as:
37
- - `ragProvider: "external-http"`
38
- - `ragApiUrl: "https://rag.example.com/search"`
39
- - `ragApiKey`
40
- - `ragNamespace`
41
- - `ragTopK`
42
- - `ragScoreThreshold`
43
- 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.
44
-
45
- ### External search contract
46
-
47
- The built-in `external-http` strategy expects:
48
-
49
- ```http
50
- POST /search
51
- Authorization: Bearer <ragApiKey>
52
- Content-Type: application/json
53
- ```
54
-
55
- ```json
56
- {
57
- "query": "search text",
58
- "topK": 5,
59
- "scoreThreshold": 0.3,
60
- "namespace": "optional-kb-namespace",
61
- "filter": {}
62
- }
63
- ```
64
-
65
- Response:
66
-
67
- ```json
68
- {
69
- "results": [
70
- {
71
- "id": "chunk-or-source-id",
72
- "content": "matched text",
73
- "score": 0.82,
74
- "metadata": {
75
- "fileId": "123",
76
- "filename": "contract.pdf",
77
- "collection": "orders",
78
- "recordId": "456",
79
- "sourceUrl": "/api/attachments/123:download"
80
- }
81
- }
82
- ]
83
- }
84
- ```
85
-
86
- 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.
87
-
88
- ### Lightweight open-source service target
89
-
90
- For a small but useful deployment, use a standalone service with:
91
-
92
- - Qdrant or LanceDB for vector search.
93
- - FastAPI or Express for `/ingest`, `/delete`, and `/search`.
94
- - A small embedding model such as `BAAI/bge-small-en-v1.5`, `intfloat/multilingual-e5-small`, or another model matching the deployment language.
95
- - A namespace per NocoBase knowledge base.
96
-
97
- Minimum API surface:
98
-
99
- - `POST /ingest`: receive `{ namespace, source, content | fileUrl | storageRef, metadata }`.
100
- - `POST /delete`: receive `{ namespace, sourceId }`.
101
- - `POST /search`: implement the contract above.
102
-
103
- 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.
104
-
105
- ### E5/OpenAI-compatible embedding
106
-
107
- 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.
108
-
109
- - embed user queries as `query: <question>`;
110
- - embed document chunks as `passage: <chunk>`;
111
- - use the same model for ingest and search;
112
- - recreate the vector collection when changing models or vector dimensions.
113
-
114
- The RAG service still owns chunking, embedding calls, vector storage, and metadata mapping. NocoBase owns the LLM service configuration and search authorization path.
1
+ # plugin-agent-orchestrator
2
+
3
+ ## Overview
4
+ Hierarchical Multi-Agent orchestration for NocoBase AI Employees. Enables Leader agents to delegate tasks to Sub-Agent employees, with detailed execution tracing and context/memory management.
5
+
6
+ ## Features
7
+ - **Hierarchical Delegation**: Allows AI Leader agents to break down complex tasks and assign them to specialized sub-agents via native dispatching.
8
+ - **Seamless Integration**: Plugs directly into the existing AI Employee framework, capturing execution spans.
9
+ - **Execution Tracking**: Monitor sub-agent task execution and nested tool calls in detail within the main chat interface.
10
+ - **External RAG Search**: Exposes `external_rag_search` so leaders and sub-agents can retrieve context from NocoBase knowledge bases, including external RAG services.
11
+
12
+ ## Usage
13
+ 1. Enable the plugin in the NocoBase Plugin Manager.
14
+ 2. Navigate to the AI Employee configuration page.
15
+ 3. Configure a primary "Leader" agent and specialized "Sub-Agent" employees.
16
+ 4. Add the built-in **AI employee task dispatching** (`dispatch-sub-agent-task`) tool to the Leader agent.
17
+ 5. Ensure the user role has access to both the Leader and Sub-Agent employees (configured via employee roles mapping).
18
+ 6. Interact with the Leader agent; it will automatically delegate tasks to the sub-agents when necessary.
19
+
20
+
21
+ ## External RAG / Embedding service
22
+
23
+ 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`.
24
+
25
+ ### Architecture
26
+
27
+ 1. NocoBase stores the source metadata:
28
+ - uploaded file attachment id, filename, storage id, URL, owner/role access, or
29
+ - datasource/collection/record id for database-backed knowledge.
30
+ 2. The external RAG service owns:
31
+ - document fetching or receiving source payloads,
32
+ - parsing/chunking,
33
+ - embedding,
34
+ - vector index,
35
+ - retrieval.
36
+ 3. NocoBase creates a knowledge base with `type = EXTERNAL_RAG` and `options` such as:
37
+ - `ragProvider: "external-http"`
38
+ - `ragApiUrl: "https://rag.example.com/search"`
39
+ - `ragApiKey`
40
+ - `ragNamespace`
41
+ - `ragTopK`
42
+ - `ragScoreThreshold`
43
+ 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.
44
+
45
+ ### External search contract
46
+
47
+ The built-in `external-http` strategy expects:
48
+
49
+ ```http
50
+ POST /search
51
+ Authorization: Bearer <ragApiKey>
52
+ Content-Type: application/json
53
+ ```
54
+
55
+ ```json
56
+ {
57
+ "query": "search text",
58
+ "topK": 5,
59
+ "scoreThreshold": 0.3,
60
+ "namespace": "optional-kb-namespace",
61
+ "filter": {}
62
+ }
63
+ ```
64
+
65
+ Response:
66
+
67
+ ```json
68
+ {
69
+ "results": [
70
+ {
71
+ "id": "chunk-or-source-id",
72
+ "content": "matched text",
73
+ "score": 0.82,
74
+ "metadata": {
75
+ "fileId": "123",
76
+ "filename": "contract.pdf",
77
+ "collection": "orders",
78
+ "recordId": "456",
79
+ "sourceUrl": "/api/attachments/123:download"
80
+ }
81
+ }
82
+ ]
83
+ }
84
+ ```
85
+
86
+ 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.
87
+
88
+ ### Lightweight open-source service target
89
+
90
+ For a small but useful deployment, use a standalone service with:
91
+
92
+ - Qdrant or LanceDB for vector search.
93
+ - FastAPI or Express for `/ingest`, `/delete`, and `/search`.
94
+ - A small embedding model such as `BAAI/bge-small-en-v1.5`, `intfloat/multilingual-e5-small`, or another model matching the deployment language.
95
+ - A namespace per NocoBase knowledge base.
96
+
97
+ Minimum API surface:
98
+
99
+ - `POST /ingest`: receive `{ namespace, source, content | fileUrl | storageRef, metadata }`.
100
+ - `POST /delete`: receive `{ namespace, sourceId }`.
101
+ - `POST /search`: implement the contract above.
102
+
103
+ 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.
104
+
105
+ ### E5/OpenAI-compatible embedding
106
+
107
+ 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.
108
+
109
+ - embed user queries as `query: <question>`;
110
+ - embed document chunks as `passage: <chunk>`;
111
+ - use the same model for ingest and search;
112
+ - recreate the vector collection when changing models or vector dimensions.
113
+
114
+ The RAG service still owns chunking, embedding calls, vector storage, and metadata mapping. NocoBase owns the LLM service configuration and search authorization path.
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "displayName.zh-CN": "代理协调器",
5
5
  "displayName.vi-VN": "Điều phối Agent",
6
6
  "description": "Native AI Employee sub-agent monitoring, policy, and memory context layer for NocoBase plugin-ai.",
7
- "version": "1.0.32",
7
+ "version": "1.0.33",
8
8
  "license": "Apache-2.0",
9
9
  "main": "dist/server/index.js",
10
10
  "keywords": [