plugin-agent-orchestrator 1.1.4 → 1.1.6
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 +204 -114
- package/dist/client/index.js +1 -1
- package/dist/client-v2/117.7565cff57c39318a.js +10 -0
- package/dist/client-v2/214.106635011859dede.js +10 -0
- package/dist/client-v2/418.41ed200e7d6da332.js +10 -0
- package/dist/client-v2/53.349fff8db80b19d4.js +10 -0
- package/dist/client-v2/981.e4a1f41cfc94a856.js +10 -0
- package/dist/client-v2/index.js +1 -1
- package/dist/externalVersion.js +7 -8
- package/dist/locale/en-US.json +226 -170
- package/dist/locale/vi-VN.json +226 -170
- package/dist/locale/zh-CN.json +226 -170
- package/dist/server/collections/agent-execution-spans.js +8 -0
- package/dist/server/collections/agent-loop-action-approvals.js +1 -0
- package/dist/server/collections/agent-loop-runs.js +7 -1
- package/dist/server/collections/agent-loop-steps.js +7 -0
- package/dist/server/collections/skill-executions.js +8 -0
- package/dist/server/plugin.js +3 -1
- package/dist/server/resources/agent-harness-profile.js +117 -0
- package/dist/server/resources/agent-knowledge-insights.js +1 -3
- package/dist/server/resources/agent-loop-approval.js +25 -0
- package/dist/server/resources/agent-loop.js +3 -1
- package/dist/server/services/AgentMemoryContextService.js +34 -0
- package/dist/server/services/HarnessCompiler.js +35 -2
- package/dist/server/services/HarnessProfileService.js +74 -9
- package/dist/server/services/HarnessSchema.js +30 -3
- package/dist/server/services/LoopPatternSchema.js +16 -1
- package/dist/server/services/LoopRunRepository.js +80 -0
- package/dist/server/services/LoopRunStateMachine.js +92 -3
- package/dist/server/services/LoopTriggerService.js +37 -0
- package/dist/server/services/LoopWorkerService.js +261 -23
- package/dist/server/services/NativeSubAgentObserver.js +165 -23
- package/dist/server/services/PluginAiRuntimeAdapter.js +16 -5
- package/dist/server/services/ToolLoopDetectionService.js +210 -0
- package/dist/server/services/VerificationService.js +66 -0
- package/dist/server/services/harness-runtime-policy.js +139 -0
- package/dist/server/skill-hub/plugin.js +36 -3
- package/dist/server/skill-hub/tasks/SkillExecutionTask.js +29 -0
- package/package.json +53 -53
- package/src/client/ApprovalsTab.tsx +2 -0
- package/src/client/OrchestratorSettings.tsx +11 -0
- package/src/client/skill-hub/components/GitSkillImport.tsx +3 -3
- package/src/client/skill-hub/components/SkillMetrics.tsx +15 -10
- package/src/client/skill-hub/index.tsx +0 -52
- package/src/client-v2/components/AgentRunsTab.tsx +576 -576
- package/src/client-v2/components/ApprovalsTab.tsx +337 -0
- package/src/client-v2/components/HarnessProfilesTab.tsx +385 -105
- package/src/client-v2/components/MemoryInspectorTab.tsx +141 -141
- package/src/client-v2/components/TracingTab.tsx +515 -515
- package/src/client-v2/hooks/useApiRequest.ts +141 -141
- package/src/client-v2/pages/ApprovalsPage.tsx +10 -0
- package/src/client-v2/plugin.tsx +6 -6
- package/src/client-v2/skill-hub/components/SkillMetrics.tsx +5 -2
- package/src/locale/en-US.json +226 -174
- package/src/locale/vi-VN.json +226 -174
- package/src/locale/zh-CN.json +226 -174
- package/src/server/__tests__/circuit-breaker.test.ts +248 -248
- package/src/server/__tests__/harness-compiler.test.ts +83 -0
- package/src/server/__tests__/harness-profile-service.test.ts +51 -0
- package/src/server/__tests__/harness-runtime-policy.test.ts +293 -0
- package/src/server/__tests__/harness-tool-plan.test.ts +24 -0
- package/src/server/__tests__/loop-approval-decision.test.ts +512 -0
- package/src/server/__tests__/loop-approval-expiry.test.ts +258 -0
- package/src/server/__tests__/loop-budget-service.test.ts +255 -255
- package/src/server/__tests__/loop-control-plane-backfill.test.ts +266 -266
- package/src/server/__tests__/loop-pattern-schema.test.ts +18 -1
- package/src/server/__tests__/loop-pattern-service.test.ts +148 -148
- package/src/server/__tests__/loop-run-state-machine.test.ts +11 -0
- package/src/server/__tests__/loop-trigger-service.test.ts +148 -0
- package/src/server/__tests__/loop-worker-claim.test.ts +341 -341
- package/src/server/__tests__/loop-worker-execution.test.ts +82 -1
- package/src/server/__tests__/native-sub-agent-observer.test.ts +288 -4
- package/src/server/__tests__/path-lock-service.test.ts +254 -254
- package/src/server/__tests__/skill-execution-task-policy.test.ts +140 -0
- package/src/server/__tests__/smoke.test.ts +162 -162
- package/src/server/__tests__/tool-loop-detection.test.ts +275 -0
- package/src/server/collections/agent-execution-spans.ts +8 -0
- package/src/server/collections/agent-harness-profile-versions.ts +26 -26
- package/src/server/collections/agent-harness-profiles.ts +71 -71
- package/src/server/collections/agent-loop-action-approvals.ts +1 -0
- package/src/server/collections/agent-loop-artifacts.ts +25 -25
- package/src/server/collections/agent-loop-circuit-states.ts +23 -23
- package/src/server/collections/agent-loop-control-settings.ts +21 -21
- package/src/server/collections/agent-loop-events.ts +98 -98
- package/src/server/collections/agent-loop-path-locks.ts +27 -27
- package/src/server/collections/agent-loop-patterns.ts +42 -42
- package/src/server/collections/agent-loop-runs.ts +7 -1
- package/src/server/collections/agent-loop-steps.ts +7 -0
- package/src/server/collections/agent-loop-usage-buckets.ts +22 -22
- package/src/server/collections/agent-loop-worktrees.ts +25 -25
- package/src/server/collections/skill-executions.ts +8 -0
- package/src/server/migrations/20260427000002-change-packages-to-text.ts +52 -52
- package/src/server/migrations/20260429000000-add-llm-fields.ts +47 -47
- package/src/server/migrations/20260429000001-fix-inputargs-json-to-text.ts +45 -45
- package/src/server/migrations/20260503000000-add-orchestrator-trace-fields.ts +33 -33
- package/src/server/migrations/20260524000000-add-agent-loop-fields-to-skill-executions.ts +31 -31
- package/src/server/migrations/20260803010000-backfill-loop-control-plane-data.ts +293 -293
- package/src/server/plugin.ts +3 -1
- package/src/server/resources/agent-harness-profile.ts +94 -0
- package/src/server/resources/agent-knowledge-insights.ts +5 -3
- package/src/server/resources/agent-loop-approval.ts +32 -0
- package/src/server/resources/agent-loop-artifact.ts +56 -56
- package/src/server/resources/agent-loop-events-stream.ts +105 -105
- package/src/server/resources/agent-loop.ts +3 -1
- package/src/server/resources/resource-helpers.ts +33 -33
- package/src/server/resources/tracing.ts +266 -266
- package/src/server/services/AgentMemoryContextService.ts +44 -0
- package/src/server/services/DurableCircuitBreakerService.ts +239 -239
- package/src/server/services/ExecutionSpanService.ts +2 -0
- package/src/server/services/HarnessCompiler.ts +37 -0
- package/src/server/services/HarnessProfileService.ts +92 -10
- package/src/server/services/HarnessSchema.ts +31 -0
- package/src/server/services/LoopBudgetService.ts +275 -275
- package/src/server/services/LoopControlService.ts +124 -124
- package/src/server/services/LoopPatternSchema.ts +19 -1
- package/src/server/services/LoopPatternService.ts +143 -143
- package/src/server/services/LoopRunRepository.ts +99 -0
- package/src/server/services/LoopRunStateMachine.ts +100 -3
- package/src/server/services/LoopSchedulerService.ts +199 -199
- package/src/server/services/LoopTriggerService.ts +42 -0
- package/src/server/services/LoopWorkerService.ts +327 -27
- package/src/server/services/NativeSubAgentObserver.ts +186 -21
- package/src/server/services/PathLockService.ts +321 -321
- package/src/server/services/PluginAiRuntimeAdapter.ts +24 -7
- package/src/server/services/ToolLoopDetectionService.ts +213 -0
- package/src/server/services/VerificationSchema.ts +31 -31
- package/src/server/services/VerificationService.ts +81 -2
- package/src/server/services/harness-runtime-policy.ts +141 -0
- package/src/server/skill-hub/plugin.ts +41 -3
- package/src/server/skill-hub/services/RegistrySkillSnapshotService.ts +235 -235
- package/src/server/skill-hub/services/__tests__/RegistrySkillSnapshotService.test.ts +61 -61
- package/src/server/skill-hub/tasks/SkillExecutionTask.ts +43 -2
- package/src/server/utils/ensure-indexes.ts +96 -96
- package/src/server/utils/logging.ts +62 -62
- package/src/server/utils/loop-pattern-context.ts +20 -20
- package/dist/client-v2/214.b063f33ba044a808.js +0 -10
- package/dist/client-v2/373.f5d5292e53c4e832.js +0 -10
- package/dist/client-v2/418.58fa350f5496efd3.js +0 -10
- package/dist/client-v2/53.9a10455323390f14.js +0 -10
- package/dist/client-v2/677.a991ce0250ff5c77.js +0 -10
- package/dist/client-v2/925.e5925bf21ed68e7a.js +0 -10
- package/src/client/AIEmployeeSelect.tsx +0 -47
- package/src/client/AIEmployeesContext.tsx +0 -102
- package/src/client/RulesTab.tsx +0 -2
- package/src/client/TracingTab.tsx +0 -436
- package/src/client/skill-hub/components/ExecutionProgress.tsx +0 -51
- package/src/client-v2/components/RulesTab.tsx +0 -2
- package/src/client-v2/pages/AgentRunsPage.tsx +0 -13
package/README.md
CHANGED
|
@@ -1,114 +1,204 @@
|
|
|
1
|
-
# plugin-agent-orchestrator
|
|
2
|
-
|
|
3
|
-
## Overview
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
###
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
- `
|
|
100
|
-
|
|
101
|
-
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
1
|
+
# plugin-agent-orchestrator
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
Agent orchestration layer for NocoBase AI Employees (plugin-ai). The plugin provides three main subsystems:
|
|
6
|
+
|
|
7
|
+
1. **Agent Loop Control Plane** — durable, policy-governed multi-step runs with a leader/maker/verifier role model, cron/event/manual triggers, budgets, approvals, and independent verification.
|
|
8
|
+
2. **Harness (Policy Profiles)** — versioned, tag-addressed policy bundles that constrain what each role may do (tools, memory, delegation, limits, isolation, observability), compiled layer-by-layer with most-restrictive-wins semantics.
|
|
9
|
+
3. **Skill Hub** — sandboxed Python/Node.js skills that AI employees can execute as tools, with async execution, human-in-the-loop review, an MCP-style surface, and Git/registry import.
|
|
10
|
+
|
|
11
|
+
On top of these, the plugin observes native sub-agent dispatching from plugin-ai, records a unified execution-span tree, injects agent memory context, and exposes an external RAG search tool.
|
|
12
|
+
|
|
13
|
+
## Agent Loop Control Plane
|
|
14
|
+
|
|
15
|
+
### Patterns
|
|
16
|
+
|
|
17
|
+
A loop pattern (`agentLoopPatterns`) defines a repeatable unit of autonomous work:
|
|
18
|
+
|
|
19
|
+
- `key`, `goalTemplate` — identity and the goal rendered for each run.
|
|
20
|
+
- `autonomyLevel` — `L1` (supervised), `L2`, `L3` (autonomous). L2/L3 require repository identity (`repositoryKey`, `repositoryRoot`, `baseRef`, `actingOn[]`) and worktree isolation (`policy.harness.isolation.requireWorktree`).
|
|
21
|
+
- `triggerType` — `manual`, `cron` (`cronExpression` + `timezone`), or `event` (`eventKey`).
|
|
22
|
+
- Role bindings — `leaderUsername`, `makerUsernames[]`, `verifierUsername` (verifier must differ from leader and makers).
|
|
23
|
+
- Per-role harness tags — `leaderHarnessTag` / `makerHarnessTag` (default `default`), `verifierHarnessTag` (default `safe`).
|
|
24
|
+
- `policy` — concurrency, per-run/daily budgets (invocations, tool calls, delegations, verifications, tokens, cost), circuit-breaker limits, path restrictions (`maxFiles`, deny list), action approval settings (`autoAllowlist`, approvers, timeout), tool-loop detection thresholds (`warnAt`/`blockAt`/`escalateAt`), and required verification checks.
|
|
25
|
+
|
|
26
|
+
### Run lifecycle
|
|
27
|
+
|
|
28
|
+
`LoopTriggerService` compiles the pattern (including layered harness compilation), snapshots role bindings and harness settings onto the run row, and enqueues it. `LoopWorkerService` claims queued runs with a lease + heartbeat, acquires path locks on `actingOn`, then drives the run:
|
|
29
|
+
|
|
30
|
+
`queued → preparing → waiting_lock → running → waiting_approval → verifying → waiting_human → succeeded | failed | canceled` (plus `paused`, `blocked`).
|
|
31
|
+
|
|
32
|
+
- **Leader** invocation plans the work but changes nothing.
|
|
33
|
+
- **Maker** invocations execute the plan, each under its own compiled harness.
|
|
34
|
+
- Tool calls gated as `ask` park the run in `waiting_approval` until the approval row is resolved via `agentLoopApprovals:decide` (approve — optionally substituting an edited input — or reject).
|
|
35
|
+
- **Tool-loop detection** (`ToolLoopDetectionService`, active in both worker and verifier) guards against repeated identical tool calls: `warnAt` injects a notice into the run, `blockAt` refuses the call, `escalateAt` escalates the run for human review.
|
|
36
|
+
- **Verifier** (via `VerificationService`) runs an independent pass and returns a JSON verdict: `pass` → `succeeded` (L1) or `waiting_human` (L2/L3); `reject` → `failed`; `escalate` → `waiting_human`. Required checks and artifact evidence ownership are enforced.
|
|
37
|
+
|
|
38
|
+
Human actions on runs: pause, resume, cancel, retry, escalate, accept result. Budgets, circuit-breaker state, usage buckets, events, steps, artifacts, and worktrees are persisted in dedicated collections.
|
|
39
|
+
|
|
40
|
+
### Sub-agent observation and memory
|
|
41
|
+
|
|
42
|
+
- `NativeSubAgentObserver` wraps plugin-ai's native `dispatch-sub-agent-task` flow: it resolves harness policy, injects memory context into the delegated question, records root/tool spans in `agentExecutionSpans`, tracks tokens/cost, and links skill executions. Legacy `delegate_*` / `dispatch_subagents_*` tools are retired.
|
|
43
|
+
- `AgentMemoryContextService` builds an `<agent_memory_context>` block from `agentMemoryContexts` records (scopes `public`, `user`, `agent_user`, plus plugin-user-memory content), trimmed to the harness-configured character limit.
|
|
44
|
+
- `AgentRegistryService` resolves leader↔sub-agent bindings from `orchestratorConfig`, model overrides, and alternative sub-agents for retry.
|
|
45
|
+
|
|
46
|
+
## Harness (Policy Profiles)
|
|
47
|
+
|
|
48
|
+
A harness profile is a versioned policy bundle addressed by a unique `tag`. Settings (validated by a strict zod schema in `HarnessSchema.ts`) have six sections:
|
|
49
|
+
|
|
50
|
+
| Section | Controls |
|
|
51
|
+
| --- | --- |
|
|
52
|
+
| `tools` | `allow` / `ask` / `deny` lists, per-tool `effects` (`read` / `write` / `external`), `trustedPreHandlerTools` |
|
|
53
|
+
| `memory` | `enabled`, `scopes` (`public` / `user` / `agent_user`), `maxChars` |
|
|
54
|
+
| `delegation` | `allowedEmployees`, `maxDepth`, `maxCount` |
|
|
55
|
+
| `limits` | `timeoutMs`, `recursionLimit`, max invocations/tool calls/tokens/cost |
|
|
56
|
+
| `isolation` | `mode` (`none` / `worktree`), `requireWorktree`, `allowedConnectors`, `networkAccess` (`deny` / `restricted` / `allow`) |
|
|
57
|
+
| `observability` | `enabled`, `tracingRetentionDays`, `captureInputs`, `captureOutputs` |
|
|
58
|
+
|
|
59
|
+
### Layered compilation
|
|
60
|
+
|
|
61
|
+
`HarnessCompiler.compileHarness()` merges an ordered list of layers with most-restrictive-wins semantics: allow-lists and scopes are intersected, `ask`/`deny` are unioned, numeric limits take the minimum, booleans AND, network access takes the strictest value. For each run role, `LoopPatternService` stacks:
|
|
62
|
+
|
|
63
|
+
`platform` (hard ceilings) → `profile:<tag>@<version>` (published profile) → `pattern` → `employee:<username>` → per-run overrides.
|
|
64
|
+
|
|
65
|
+
The compiled result is persisted on the run as an immutable snapshot (`leaderHarnessSnapshot`, per-maker `makerHarnessSnapshot`, `verifierHarnessSnapshot`), so runs always execute against the policy that was in force at enqueue time.
|
|
66
|
+
|
|
67
|
+
### Tool planning
|
|
68
|
+
|
|
69
|
+
At invocation time, `PluginAiRuntimeAdapter` converts the compiled harness into a tool plan: `deny` > `ask` > `allow`. Tools not explicitly allowed become `ask`; allowed tools with `write`/`external` effects stay `ask` unless listed in `trustedPreHandlerTools`. `ask` tools are attached without auto-call so they interrupt for approval; unenforceable system tools (e.g. web search) are blocked at the source.
|
|
70
|
+
|
|
71
|
+
### Versioning
|
|
72
|
+
|
|
73
|
+
`HarnessProfileService` manages draft/publish lifecycle over `agentHarnessProfileVersions`: create draft → update draft → publish (points the profile's `currentVersionId` at the published version). One open draft per profile — `saveDraft` writes into the latest unpublished draft and only starts a new version once the previous one shipped, keeping the version history a clean publish trail. `createProfile` bootstraps a profile together with its first published version atomically, and version numbering is row-locked so concurrent saves/publishes cannot collide. Published versions are immutable. Profiles are resolved by tag via `getPublishedByTag(tag)`. Seeded profiles: `default`, `safe`, `file-heavy`.
|
|
74
|
+
|
|
75
|
+
## Skill Hub
|
|
76
|
+
|
|
77
|
+
### Skills
|
|
78
|
+
|
|
79
|
+
A skill (`skillDefinitions`) is a sandboxed Python or Node.js code unit with:
|
|
80
|
+
|
|
81
|
+
- immutable `toolName`, `title`, `description`, `instructions`;
|
|
82
|
+
- `codeTemplate` with `{{placeholder}}` rendering and a JSON Schema `inputSchema`;
|
|
83
|
+
- optional `interactionSchema` for human-in-the-loop review UI;
|
|
84
|
+
- `packages`, `timeoutSeconds`, `maxOutputSizeMb`, `enabled`, `autoCall`;
|
|
85
|
+
- `toolScope` (`CUSTOM` / `GENERAL` / `SPECIFIED`) controlling visibility across AI employees;
|
|
86
|
+
- storage source: database (zip upload), local, s3, plugin template, or Git.
|
|
87
|
+
|
|
88
|
+
### Execution
|
|
89
|
+
|
|
90
|
+
`skill_hub_execute` and per-skill `skill_hub_<toolName>` tools validate input, check per-agent access (`SkillAccessService`), apply a per-user rate limit, create a `skillExecutions` row, and publish `skill-hub.task`. Sandbox workers claim executions, render and validate the code, run it in a sandbox, stream progress, and store stdout/stderr/output files (downloadable via `skillHub:download`). A poller recovers stale executions. Executions link into the tracing graph via `agentExecutionSpans` (span type `skill`).
|
|
91
|
+
|
|
92
|
+
### MCP surface
|
|
93
|
+
|
|
94
|
+
The Skill Hub exposes an MCP-style server surface: `skillHub:mcpListTools` lists enabled skills as `{name, description, inputSchema}` tools; `skillHub:mcpCallTool` executes one and returns MCP content (including a file manifest).
|
|
95
|
+
|
|
96
|
+
### Import and registry
|
|
97
|
+
|
|
98
|
+
- **Git import**: `gitListSkills` / `gitSyncSkills` read a `skills.json` manifest and `SKILL.md` frontmatter through plugin-git-manager (optional peer dependency).
|
|
99
|
+
- **Registry**: `RegistrySkillInstallationService` installs registry package versions into local `skillDefinitions` (disabled by default, with rollback chain), and `RegistrySkillSnapshotService` exports opt-in snapshots of local skills for an external registry plugin.
|
|
100
|
+
|
|
101
|
+
### Human-in-the-loop review
|
|
102
|
+
|
|
103
|
+
`skillLoopConfigs` stores review templates (prompt + schema) per skill; the chat UI renders approval cards for skill executions that require review.
|
|
104
|
+
|
|
105
|
+
## External RAG Search
|
|
106
|
+
|
|
107
|
+
The plugin registers the `external_rag_search` tool so leaders and sub-agents can retrieve context from NocoBase knowledge bases, including external RAG services. Source ownership stays in NocoBase; chunking, embedding, vector storage, and retrieval live in an external lightweight RAG service. The tool calls `plugin-knowledge-base.searchKnowledgeBases()`, so access control and mixed local/external search stay centralized.
|
|
108
|
+
|
|
109
|
+
Knowledge bases of type `EXTERNAL_RAG` carry options such as `ragProvider` (`external-http` or `e5-http`), `ragApiUrl`, `ragApiKey`, `ragNamespace`, `ragTopK`, `ragScoreThreshold`.
|
|
110
|
+
|
|
111
|
+
### External search contract
|
|
112
|
+
|
|
113
|
+
The built-in `external-http` strategy expects:
|
|
114
|
+
|
|
115
|
+
```http
|
|
116
|
+
POST /search
|
|
117
|
+
Authorization: Bearer <ragApiKey>
|
|
118
|
+
Content-Type: application/json
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
```json
|
|
122
|
+
{
|
|
123
|
+
"query": "search text",
|
|
124
|
+
"topK": 5,
|
|
125
|
+
"scoreThreshold": 0.3,
|
|
126
|
+
"namespace": "optional-kb-namespace",
|
|
127
|
+
"filter": {}
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Response:
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{
|
|
135
|
+
"results": [
|
|
136
|
+
{
|
|
137
|
+
"id": "chunk-or-source-id",
|
|
138
|
+
"content": "matched text",
|
|
139
|
+
"score": 0.82,
|
|
140
|
+
"metadata": {
|
|
141
|
+
"fileId": "123",
|
|
142
|
+
"filename": "contract.pdf",
|
|
143
|
+
"collection": "orders",
|
|
144
|
+
"recordId": "456",
|
|
145
|
+
"sourceUrl": "/api/attachments/123:download"
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
]
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Every result must return enough metadata for NocoBase to resolve the original source: `fileId`/`filename` for files, or `collection`/`recordId` for datasource records.
|
|
153
|
+
|
|
154
|
+
For E5-family models behind an OpenAI-compatible `/v1/embeddings` API, use `ragProvider: "e5-http"`: queries are embedded as `query: <question>`, chunks as `passage: <chunk>`, and the vector collection must be recreated when the model or vector dimensions change.
|
|
155
|
+
|
|
156
|
+
## UI
|
|
157
|
+
|
|
158
|
+
Settings pages under **AI Employee → Agent Orchestrator** (both v1 client and client-v2):
|
|
159
|
+
|
|
160
|
+
| Tab | Purpose |
|
|
161
|
+
| --- | --- |
|
|
162
|
+
| Native Monitor | Loop run list with status, budgets, approvals |
|
|
163
|
+
| Execution Tracing | Span tree of sub-agent and tool executions |
|
|
164
|
+
| Policy Profiles | Harness profile CRUD with draft/publish versioning and version history |
|
|
165
|
+
| Approvals | Pending tool-call/escalation approvals; approve or reject with optional edited input |
|
|
166
|
+
| Agent Bindings | Leader↔sub-agent binding configuration |
|
|
167
|
+
| Knowledge Access | Per-agent knowledge base access matrix |
|
|
168
|
+
| Retrieval Trace | Retrieval tracing for knowledge lookups |
|
|
169
|
+
| Memory Inspector | Inspect agent memory context records |
|
|
170
|
+
| Skill Hub Definitions | Skill CRUD, editor, test panel, Git import |
|
|
171
|
+
| Execution History | Skill execution logs and output files |
|
|
172
|
+
| Skill Review Settings | Human-in-the-loop review templates |
|
|
173
|
+
| Metrics | Skill usage metrics |
|
|
174
|
+
|
|
175
|
+
## API Resources
|
|
176
|
+
|
|
177
|
+
- `agentLoops` — list, get, runNow, pause, resume, cancel, retry, escalate, acceptResult, status
|
|
178
|
+
- `agentLoopApprovals` — list, get, decide
|
|
179
|
+
- `agentLoopArtifactsView` — list, get
|
|
180
|
+
- `agentLoopEventsStream` — stream
|
|
181
|
+
- `agentMonitor` — list, get, sync
|
|
182
|
+
- `agentKnowledgeInsights` — accessMatrix, retrievalTrace, memoryPreview
|
|
183
|
+
- `orchestratorTracing` — list, get
|
|
184
|
+
- `skillHub` — download, test, initEnv, clearStorage, mcpListTools, mcpCallTool, listTemplates, gitListSkills, gitSyncSkills
|
|
185
|
+
- `agentHarnessProfiles` — standard CRUD plus listVersions, saveDraft, publish, createProfile, validate
|
|
186
|
+
- Standard CRUD on `skillDefinitions`, `skillExecutions`, `agentMemoryContexts`, and related collections
|
|
187
|
+
|
|
188
|
+
## Collections
|
|
189
|
+
|
|
190
|
+
Agent loops: `agentLoopPatterns`, `agentLoopRuns`, `agentLoopSteps`, `agentLoopEvents`, `agentLoopActionApprovals`, `agentLoopArtifacts`, `agentLoopCircuitStates`, `agentLoopControlSettings`, `agentLoopPathLocks`, `agentLoopUsageBuckets`, `agentLoopWorktrees`.
|
|
191
|
+
|
|
192
|
+
Harness: `agentHarnessProfiles`, `agentHarnessProfileVersions`.
|
|
193
|
+
|
|
194
|
+
Observation/memory: `agentExecutionSpans`, `orchestratorConfig`, `orchestratorLogs`, `agentMemoryContexts`.
|
|
195
|
+
|
|
196
|
+
Skill Hub: `skillDefinitions`, `skillExecutions`, `skillLoopConfigs`, `skillWorkerConfigs`, `skillRegistryInstallations`.
|
|
197
|
+
|
|
198
|
+
## Usage
|
|
199
|
+
|
|
200
|
+
1. Enable the plugin in the NocoBase Plugin Manager (requires plugin-ai; plugin-git-manager is optional for Git skill import).
|
|
201
|
+
2. Configure **Policy Profiles** (harness tags) for your risk levels — the seeded `default`, `safe`, and `file-heavy` profiles are a starting point.
|
|
202
|
+
3. For sub-agent delegation: configure leader↔sub-agent bindings in **Agent Bindings**, add the built-in **AI employee task dispatching** (`dispatch-sub-agent-task`) tool to the leader, and ensure the user role can access both employees.
|
|
203
|
+
4. For autonomous loops: create a pattern (goal, autonomy level, trigger, roles, harness tags, policy), then trigger runs manually, by cron, or by event; monitor runs in **Native Monitor** and resolve approvals/verification escalations there.
|
|
204
|
+
5. For skills: define skills in **Skill Hub Definitions** (or import from Git/registry), test them with the test panel, then bind the generated `skill_hub_*` tools to AI employees.
|