network-ai 3.0.0
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/LICENSE +21 -0
- package/QUICKSTART.md +260 -0
- package/README.md +604 -0
- package/SKILL.md +568 -0
- package/dist/adapters/adapter-registry.d.ts +94 -0
- package/dist/adapters/adapter-registry.d.ts.map +1 -0
- package/dist/adapters/adapter-registry.js +355 -0
- package/dist/adapters/adapter-registry.js.map +1 -0
- package/dist/adapters/agno-adapter.d.ts +112 -0
- package/dist/adapters/agno-adapter.d.ts.map +1 -0
- package/dist/adapters/agno-adapter.js +140 -0
- package/dist/adapters/agno-adapter.js.map +1 -0
- package/dist/adapters/autogen-adapter.d.ts +67 -0
- package/dist/adapters/autogen-adapter.d.ts.map +1 -0
- package/dist/adapters/autogen-adapter.js +141 -0
- package/dist/adapters/autogen-adapter.js.map +1 -0
- package/dist/adapters/base-adapter.d.ts +51 -0
- package/dist/adapters/base-adapter.d.ts.map +1 -0
- package/dist/adapters/base-adapter.js +103 -0
- package/dist/adapters/base-adapter.js.map +1 -0
- package/dist/adapters/crewai-adapter.d.ts +72 -0
- package/dist/adapters/crewai-adapter.d.ts.map +1 -0
- package/dist/adapters/crewai-adapter.js +148 -0
- package/dist/adapters/crewai-adapter.js.map +1 -0
- package/dist/adapters/custom-adapter.d.ts +74 -0
- package/dist/adapters/custom-adapter.d.ts.map +1 -0
- package/dist/adapters/custom-adapter.js +142 -0
- package/dist/adapters/custom-adapter.js.map +1 -0
- package/dist/adapters/dspy-adapter.d.ts +70 -0
- package/dist/adapters/dspy-adapter.d.ts.map +1 -0
- package/dist/adapters/dspy-adapter.js +127 -0
- package/dist/adapters/dspy-adapter.js.map +1 -0
- package/dist/adapters/haystack-adapter.d.ts +83 -0
- package/dist/adapters/haystack-adapter.d.ts.map +1 -0
- package/dist/adapters/haystack-adapter.js +149 -0
- package/dist/adapters/haystack-adapter.js.map +1 -0
- package/dist/adapters/index.d.ts +47 -0
- package/dist/adapters/index.d.ts.map +1 -0
- package/dist/adapters/index.js +56 -0
- package/dist/adapters/index.js.map +1 -0
- package/dist/adapters/langchain-adapter.d.ts +51 -0
- package/dist/adapters/langchain-adapter.d.ts.map +1 -0
- package/dist/adapters/langchain-adapter.js +134 -0
- package/dist/adapters/langchain-adapter.js.map +1 -0
- package/dist/adapters/llamaindex-adapter.d.ts +89 -0
- package/dist/adapters/llamaindex-adapter.d.ts.map +1 -0
- package/dist/adapters/llamaindex-adapter.js +135 -0
- package/dist/adapters/llamaindex-adapter.js.map +1 -0
- package/dist/adapters/mcp-adapter.d.ts +90 -0
- package/dist/adapters/mcp-adapter.d.ts.map +1 -0
- package/dist/adapters/mcp-adapter.js +200 -0
- package/dist/adapters/mcp-adapter.js.map +1 -0
- package/dist/adapters/openai-assistants-adapter.d.ts +94 -0
- package/dist/adapters/openai-assistants-adapter.d.ts.map +1 -0
- package/dist/adapters/openai-assistants-adapter.js +130 -0
- package/dist/adapters/openai-assistants-adapter.js.map +1 -0
- package/dist/adapters/openclaw-adapter.d.ts +21 -0
- package/dist/adapters/openclaw-adapter.d.ts.map +1 -0
- package/dist/adapters/openclaw-adapter.js +140 -0
- package/dist/adapters/openclaw-adapter.js.map +1 -0
- package/dist/adapters/semantic-kernel-adapter.d.ts +73 -0
- package/dist/adapters/semantic-kernel-adapter.d.ts.map +1 -0
- package/dist/adapters/semantic-kernel-adapter.js +123 -0
- package/dist/adapters/semantic-kernel-adapter.js.map +1 -0
- package/dist/index.d.ts +379 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1428 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/blackboard-validator.d.ts +205 -0
- package/dist/lib/blackboard-validator.d.ts.map +1 -0
- package/dist/lib/blackboard-validator.js +756 -0
- package/dist/lib/blackboard-validator.js.map +1 -0
- package/dist/lib/locked-blackboard.d.ts +174 -0
- package/dist/lib/locked-blackboard.d.ts.map +1 -0
- package/dist/lib/locked-blackboard.js +654 -0
- package/dist/lib/locked-blackboard.js.map +1 -0
- package/dist/lib/swarm-utils.d.ts +136 -0
- package/dist/lib/swarm-utils.d.ts.map +1 -0
- package/dist/lib/swarm-utils.js +510 -0
- package/dist/lib/swarm-utils.js.map +1 -0
- package/dist/security.d.ts +269 -0
- package/dist/security.d.ts.map +1 -0
- package/dist/security.js +713 -0
- package/dist/security.js.map +1 -0
- package/package.json +84 -0
- package/scripts/blackboard.py +819 -0
- package/scripts/check_permission.py +331 -0
- package/scripts/revoke_token.py +243 -0
- package/scripts/swarm_guard.py +1140 -0
- package/scripts/validate_token.py +97 -0
- package/types/agent-adapter.d.ts +244 -0
- package/types/openclaw-core.d.ts +52 -0
package/SKILL.md
ADDED
|
@@ -0,0 +1,568 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: swarm-orchestrator
|
|
3
|
+
description: Multi-agent swarm orchestration for complex workflows. Use when coordinating multiple agents, delegating tasks between sessions, managing shared state via blackboard, or enforcing permission walls for DATABASE/PAYMENTS/EMAIL access. Triggers on: agent coordination, task delegation, parallel execution, permission requests, blackboard state management.
|
|
4
|
+
metadata: { "openclaw": { "emoji": "🐝", "homepage": "https://github.com/jovanSAPFIONEER/Network-AI" } }
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Swarm Orchestrator Skill
|
|
8
|
+
|
|
9
|
+
Multi-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.
|
|
10
|
+
|
|
11
|
+
## 🎯 Orchestrator System Instructions
|
|
12
|
+
|
|
13
|
+
**You are the Orchestrator Agent** responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:
|
|
14
|
+
|
|
15
|
+
### Core Responsibilities
|
|
16
|
+
|
|
17
|
+
1. **DECOMPOSE** complex prompts into 3 specialized sub-tasks
|
|
18
|
+
2. **DELEGATE** using the budget-aware handoff protocol
|
|
19
|
+
3. **VERIFY** results on the blackboard before committing
|
|
20
|
+
4. **SYNTHESIZE** final output only after all validations pass
|
|
21
|
+
|
|
22
|
+
### Task Decomposition Protocol
|
|
23
|
+
|
|
24
|
+
When you receive a complex request, decompose it into exactly **3 sub-tasks**:
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
┌─────────────────────────────────────────────────────────────────┐
|
|
28
|
+
│ COMPLEX USER REQUEST │
|
|
29
|
+
└─────────────────────────────────────────────────────────────────┘
|
|
30
|
+
│
|
|
31
|
+
▼
|
|
32
|
+
┌─────────────────────┼─────────────────────┐
|
|
33
|
+
│ │ │
|
|
34
|
+
▼ ▼ ▼
|
|
35
|
+
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
|
36
|
+
│ SUB-TASK 1 │ │ SUB-TASK 2 │ │ SUB-TASK 3 │
|
|
37
|
+
│ data_analyst │ │ risk_assessor │ │strategy_advisor│
|
|
38
|
+
│ (DATA) │ │ (VERIFY) │ │ (RECOMMEND) │
|
|
39
|
+
└───────────────┘ └───────────────┘ └───────────────┘
|
|
40
|
+
│ │ │
|
|
41
|
+
└─────────────────────┼─────────────────────┘
|
|
42
|
+
▼
|
|
43
|
+
┌───────────────┐
|
|
44
|
+
│ SYNTHESIZE │
|
|
45
|
+
│ orchestrator │
|
|
46
|
+
└───────────────┘
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
**Decomposition Template:**
|
|
50
|
+
```
|
|
51
|
+
TASK DECOMPOSITION for: "{user_request}"
|
|
52
|
+
|
|
53
|
+
Sub-Task 1 (DATA): [data_analyst]
|
|
54
|
+
- Objective: Extract/process raw data
|
|
55
|
+
- Output: Structured JSON with metrics
|
|
56
|
+
|
|
57
|
+
Sub-Task 2 (VERIFY): [risk_assessor]
|
|
58
|
+
- Objective: Validate data quality & compliance
|
|
59
|
+
- Output: Validation report with confidence score
|
|
60
|
+
|
|
61
|
+
Sub-Task 3 (RECOMMEND): [strategy_advisor]
|
|
62
|
+
- Objective: Generate actionable insights
|
|
63
|
+
- Output: Recommendations with rationale
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Budget-Aware Handoff Protocol
|
|
67
|
+
|
|
68
|
+
**CRITICAL:** Before EVERY `sessions_send`, call the handoff interceptor:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# ALWAYS run this BEFORE sessions_send
|
|
72
|
+
python {baseDir}/scripts/swarm_guard.py intercept-handoff \
|
|
73
|
+
--task-id "task_001" \
|
|
74
|
+
--from orchestrator \
|
|
75
|
+
--to data_analyst \
|
|
76
|
+
--message "Analyze Q4 revenue data"
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**Decision Logic:**
|
|
80
|
+
```
|
|
81
|
+
IF result.allowed == true:
|
|
82
|
+
→ Proceed with sessions_send
|
|
83
|
+
→ Note tokens_spent and remaining_budget
|
|
84
|
+
ELSE:
|
|
85
|
+
→ STOP - Do NOT call sessions_send
|
|
86
|
+
→ Report blocked reason to user
|
|
87
|
+
→ Consider: reduce scope or abort task
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Pre-Commit Verification Workflow
|
|
91
|
+
|
|
92
|
+
Before returning final results to the user:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
# Step 1: Check all sub-task results on blackboard
|
|
96
|
+
python {baseDir}/scripts/blackboard.py read "task:001:data_analyst"
|
|
97
|
+
python {baseDir}/scripts/blackboard.py read "task:001:risk_assessor"
|
|
98
|
+
python {baseDir}/scripts/blackboard.py read "task:001:strategy_advisor"
|
|
99
|
+
|
|
100
|
+
# Step 2: Validate each result
|
|
101
|
+
python {baseDir}/scripts/swarm_guard.py validate-result \
|
|
102
|
+
--task-id "task_001" \
|
|
103
|
+
--agent data_analyst \
|
|
104
|
+
--result '{"status":"success","output":{...},"confidence":0.85}'
|
|
105
|
+
|
|
106
|
+
# Step 3: Supervisor review (checks all issues)
|
|
107
|
+
python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"
|
|
108
|
+
|
|
109
|
+
# Step 4: Only if APPROVED, commit final state
|
|
110
|
+
python {baseDir}/scripts/blackboard.py write "task:001:final" \
|
|
111
|
+
'{"status":"SUCCESS","output":{...}}'
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
**Verdict Handling:**
|
|
115
|
+
| Verdict | Action |
|
|
116
|
+
|---------|--------|
|
|
117
|
+
| `APPROVED` | Commit and return results to user |
|
|
118
|
+
| `WARNING` | Review issues, fix if possible, then commit |
|
|
119
|
+
| `BLOCKED` | Do NOT return results. Report failure. |
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## When to Use This Skill
|
|
124
|
+
|
|
125
|
+
- **Task Delegation**: Route work to specialized agents (data_analyst, strategy_advisor, risk_assessor)
|
|
126
|
+
- **Parallel Execution**: Run multiple agents simultaneously and synthesize results
|
|
127
|
+
- **Permission Wall**: Gate access to SAP_API, FINANCIAL_API, or DATA_EXPORT operations
|
|
128
|
+
- **Shared Blackboard**: Coordinate agent state via persistent markdown file
|
|
129
|
+
|
|
130
|
+
## Quick Start
|
|
131
|
+
|
|
132
|
+
### 1. Initialize Budget (FIRST!)
|
|
133
|
+
|
|
134
|
+
**Always initialize a budget before any multi-agent task:**
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
python {baseDir}/scripts/swarm_guard.py budget-init \
|
|
138
|
+
--task-id "task_001" \
|
|
139
|
+
--budget 10000 \
|
|
140
|
+
--description "Q4 Financial Analysis"
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### 2. Delegate a Task to Another Session
|
|
144
|
+
|
|
145
|
+
Use OpenClaw's built-in session tools to delegate work:
|
|
146
|
+
|
|
147
|
+
```
|
|
148
|
+
sessions_list # See available sessions/agents
|
|
149
|
+
sessions_send # Send task to another session
|
|
150
|
+
sessions_history # Check results from delegated work
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**Example delegation prompt:**
|
|
154
|
+
```
|
|
155
|
+
Use sessions_send to ask the data_analyst session to:
|
|
156
|
+
"Analyze Q4 revenue trends from the SAP export data and summarize key insights"
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### 3. Check Permission Before API Access
|
|
160
|
+
|
|
161
|
+
Before accessing SAP or Financial APIs, evaluate the request:
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
# Run the permission checker script
|
|
165
|
+
python {baseDir}/scripts/check_permission.py \
|
|
166
|
+
--agent "data_analyst" \
|
|
167
|
+
--resource "SAP_API" \
|
|
168
|
+
--justification "Need Q4 invoice data for quarterly report" \
|
|
169
|
+
--scope "read:invoices"
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
The script will output a grant token if approved, or denial reason if rejected.
|
|
173
|
+
|
|
174
|
+
### 4. Use the Shared Blackboard
|
|
175
|
+
|
|
176
|
+
Read/write coordination state:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
# Write to blackboard
|
|
180
|
+
python {baseDir}/scripts/blackboard.py write "task:q4_analysis" '{"status": "in_progress", "agent": "data_analyst"}'
|
|
181
|
+
|
|
182
|
+
# Read from blackboard
|
|
183
|
+
python {baseDir}/scripts/blackboard.py read "task:q4_analysis"
|
|
184
|
+
|
|
185
|
+
# List all entries
|
|
186
|
+
python {baseDir}/scripts/blackboard.py list
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
## Agent-to-Agent Handoff Protocol
|
|
190
|
+
|
|
191
|
+
When delegating tasks between agents/sessions:
|
|
192
|
+
|
|
193
|
+
### Step 1: Initialize Budget & Check Capacity
|
|
194
|
+
```bash
|
|
195
|
+
# Initialize budget (if not already done)
|
|
196
|
+
python {baseDir}/scripts/swarm_guard.py budget-init --task-id "task_001" --budget 10000
|
|
197
|
+
|
|
198
|
+
# Check current status
|
|
199
|
+
python {baseDir}/scripts/swarm_guard.py budget-check --task-id "task_001"
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Step 2: Identify Target Agent
|
|
203
|
+
```
|
|
204
|
+
sessions_list # Find available agents
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Common agent types:
|
|
208
|
+
| Agent | Specialty |
|
|
209
|
+
|-------|-----------|
|
|
210
|
+
| `data_analyst` | Data processing, SQL, analytics |
|
|
211
|
+
| `strategy_advisor` | Business strategy, recommendations |
|
|
212
|
+
| `risk_assessor` | Risk analysis, compliance checks |
|
|
213
|
+
| `orchestrator` | Coordination, task decomposition |
|
|
214
|
+
|
|
215
|
+
### Step 3: Intercept Before Handoff (REQUIRED)
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
# This checks budget AND handoff limits before allowing the call
|
|
219
|
+
python {baseDir}/scripts/swarm_guard.py intercept-handoff \
|
|
220
|
+
--task-id "task_001" \
|
|
221
|
+
--from orchestrator \
|
|
222
|
+
--to data_analyst \
|
|
223
|
+
--message "Analyze Q4 data" \
|
|
224
|
+
--artifact # Include if expecting output
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
**If ALLOWED:** Proceed to Step 4
|
|
228
|
+
**If BLOCKED:** Stop - do not call sessions_send
|
|
229
|
+
|
|
230
|
+
### Step 4: Construct Handoff Message
|
|
231
|
+
|
|
232
|
+
Include these fields in your delegation:
|
|
233
|
+
- **instruction**: Clear task description
|
|
234
|
+
- **context**: Relevant background information
|
|
235
|
+
- **constraints**: Any limitations or requirements
|
|
236
|
+
- **expectedOutput**: What format/content you need back
|
|
237
|
+
|
|
238
|
+
### Step 5: Send via sessions_send
|
|
239
|
+
|
|
240
|
+
```
|
|
241
|
+
sessions_send to data_analyst:
|
|
242
|
+
"[HANDOFF]
|
|
243
|
+
Instruction: Analyze Q4 revenue by product category
|
|
244
|
+
Context: Using SAP export from ./data/q4_export.csv
|
|
245
|
+
Constraints: Focus on top 5 categories only
|
|
246
|
+
Expected Output: JSON summary with category, revenue, growth_pct
|
|
247
|
+
[/HANDOFF]"
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Step 4: Check Results
|
|
251
|
+
|
|
252
|
+
```
|
|
253
|
+
sessions_history data_analyst # Get the response
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## Permission Wall (AuthGuardian)
|
|
257
|
+
|
|
258
|
+
**CRITICAL**: Always check permissions before accessing:
|
|
259
|
+
- `SAP_API` - SAP system connections
|
|
260
|
+
- `FINANCIAL_API` - Financial data services
|
|
261
|
+
- `EXTERNAL_SERVICE` - Third-party APIs
|
|
262
|
+
- `DATA_EXPORT` - Exporting sensitive data
|
|
263
|
+
|
|
264
|
+
### Permission Evaluation Criteria
|
|
265
|
+
|
|
266
|
+
| Factor | Weight | Criteria |
|
|
267
|
+
|--------|--------|----------|
|
|
268
|
+
| Justification | 40% | Must explain specific task need |
|
|
269
|
+
| Trust Level | 30% | Agent's established trust score |
|
|
270
|
+
| Risk Assessment | 30% | Resource sensitivity + scope breadth |
|
|
271
|
+
|
|
272
|
+
### Using the Permission Script
|
|
273
|
+
|
|
274
|
+
```bash
|
|
275
|
+
# Request permission
|
|
276
|
+
python {baseDir}/scripts/check_permission.py \
|
|
277
|
+
--agent "your_agent_id" \
|
|
278
|
+
--resource "FINANCIAL_API" \
|
|
279
|
+
--justification "Generating quarterly financial summary for board presentation" \
|
|
280
|
+
--scope "read:revenue,read:expenses"
|
|
281
|
+
|
|
282
|
+
# Output if approved:
|
|
283
|
+
# ✅ GRANTED
|
|
284
|
+
# Token: grant_a1b2c3d4e5f6
|
|
285
|
+
# Expires: 2026-02-04T15:30:00Z
|
|
286
|
+
# Restrictions: read_only, no_pii_fields, audit_required
|
|
287
|
+
|
|
288
|
+
# Output if denied:
|
|
289
|
+
# ❌ DENIED
|
|
290
|
+
# Reason: Justification is insufficient. Please provide specific task context.
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
### Restriction Types
|
|
294
|
+
|
|
295
|
+
| Resource | Default Restrictions |
|
|
296
|
+
|----------|---------------------|
|
|
297
|
+
| SAP_API | `read_only`, `max_records:100` |
|
|
298
|
+
| FINANCIAL_API | `read_only`, `no_pii_fields`, `audit_required` |
|
|
299
|
+
| EXTERNAL_SERVICE | `rate_limit:10_per_minute` |
|
|
300
|
+
| DATA_EXPORT | `anonymize_pii`, `local_only` |
|
|
301
|
+
|
|
302
|
+
## Shared Blackboard Pattern
|
|
303
|
+
|
|
304
|
+
The blackboard (`swarm-blackboard.md`) is a markdown file for agent coordination:
|
|
305
|
+
|
|
306
|
+
```markdown
|
|
307
|
+
# Swarm Blackboard
|
|
308
|
+
Last Updated: 2026-02-04T10:30:00Z
|
|
309
|
+
|
|
310
|
+
## Knowledge Cache
|
|
311
|
+
### task:q4_analysis
|
|
312
|
+
{"status": "completed", "result": {...}, "agent": "data_analyst"}
|
|
313
|
+
|
|
314
|
+
### cache:revenue_summary
|
|
315
|
+
{"q4_total": 1250000, "growth": 0.15}
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
### Blackboard Operations
|
|
319
|
+
|
|
320
|
+
```bash
|
|
321
|
+
# Write with TTL (expires after 1 hour)
|
|
322
|
+
python {baseDir}/scripts/blackboard.py write "cache:temp_data" '{"value": 123}' --ttl 3600
|
|
323
|
+
|
|
324
|
+
# Read (returns null if expired)
|
|
325
|
+
python {baseDir}/scripts/blackboard.py read "cache:temp_data"
|
|
326
|
+
|
|
327
|
+
# Delete
|
|
328
|
+
python {baseDir}/scripts/blackboard.py delete "cache:temp_data"
|
|
329
|
+
|
|
330
|
+
# Get full snapshot
|
|
331
|
+
python {baseDir}/scripts/blackboard.py snapshot
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
## Parallel Execution
|
|
335
|
+
|
|
336
|
+
For tasks requiring multiple agent perspectives:
|
|
337
|
+
|
|
338
|
+
### Strategy 1: Merge (Default)
|
|
339
|
+
Combine all agent outputs into unified result.
|
|
340
|
+
```
|
|
341
|
+
Ask data_analyst AND strategy_advisor to both analyze the dataset.
|
|
342
|
+
Merge their insights into a comprehensive report.
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
### Strategy 2: Vote
|
|
346
|
+
Use when you need consensus - pick the result with highest confidence.
|
|
347
|
+
|
|
348
|
+
### Strategy 3: First-Success
|
|
349
|
+
Use for redundancy - take first successful result.
|
|
350
|
+
|
|
351
|
+
### Strategy 4: Chain
|
|
352
|
+
Sequential processing - output of one feeds into next.
|
|
353
|
+
|
|
354
|
+
### Example Parallel Workflow
|
|
355
|
+
|
|
356
|
+
```
|
|
357
|
+
1. sessions_send to data_analyst: "Extract key metrics from Q4 data"
|
|
358
|
+
2. sessions_send to risk_assessor: "Identify compliance risks in Q4 data"
|
|
359
|
+
3. sessions_send to strategy_advisor: "Recommend actions based on Q4 trends"
|
|
360
|
+
4. Wait for all responses via sessions_history
|
|
361
|
+
5. Synthesize: Combine metrics + risks + recommendations into executive summary
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
## Security Considerations
|
|
365
|
+
|
|
366
|
+
1. **Never bypass the permission wall** for DATABASE/PAYMENTS APIs
|
|
367
|
+
2. **Always include justification** explaining the business need
|
|
368
|
+
3. **Use minimal scope** - request only what you need
|
|
369
|
+
4. **Check token expiry** - tokens are valid for 5 minutes
|
|
370
|
+
5. **Audit trail** - all permission requests are logged
|
|
371
|
+
|
|
372
|
+
## 📝 Audit Trail Requirements (MANDATORY)
|
|
373
|
+
|
|
374
|
+
**Every sensitive action MUST be logged to `data/audit_log.jsonl`** to maintain compliance and enable forensic analysis.
|
|
375
|
+
|
|
376
|
+
### What Gets Logged Automatically
|
|
377
|
+
|
|
378
|
+
The scripts automatically log these events:
|
|
379
|
+
- `permission_granted` - When access is approved
|
|
380
|
+
- `permission_denied` - When access is rejected
|
|
381
|
+
- `permission_revoked` - When a token is manually revoked
|
|
382
|
+
- `ttl_cleanup` - When expired tokens are purged
|
|
383
|
+
- `result_validated` / `result_rejected` - Swarm Guard validations
|
|
384
|
+
|
|
385
|
+
### Log Entry Format
|
|
386
|
+
|
|
387
|
+
```json
|
|
388
|
+
{
|
|
389
|
+
"timestamp": "2026-02-04T10:30:00+00:00",
|
|
390
|
+
"action": "permission_granted",
|
|
391
|
+
"details": {
|
|
392
|
+
"agent_id": "data_analyst",
|
|
393
|
+
"resource_type": "DATABASE",
|
|
394
|
+
"justification": "Q4 revenue analysis",
|
|
395
|
+
"token": "grant_abc123...",
|
|
396
|
+
"restrictions": ["read_only", "max_records:100"]
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
### Reading the Audit Log
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
# View recent entries (last 10)
|
|
405
|
+
tail -10 {baseDir}/data/audit_log.jsonl
|
|
406
|
+
|
|
407
|
+
# Search for specific agent
|
|
408
|
+
grep "data_analyst" {baseDir}/data/audit_log.jsonl
|
|
409
|
+
|
|
410
|
+
# Count actions by type
|
|
411
|
+
cat {baseDir}/data/audit_log.jsonl | jq -r '.action' | sort | uniq -c
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
### Custom Audit Entries
|
|
415
|
+
|
|
416
|
+
If you perform a sensitive action manually, log it:
|
|
417
|
+
|
|
418
|
+
```python
|
|
419
|
+
import json
|
|
420
|
+
from datetime import datetime, timezone
|
|
421
|
+
from pathlib import Path
|
|
422
|
+
|
|
423
|
+
audit_file = Path("{baseDir}/data/audit_log.jsonl")
|
|
424
|
+
entry = {
|
|
425
|
+
"timestamp": datetime.now(timezone.utc).isoformat(),
|
|
426
|
+
"action": "manual_data_access",
|
|
427
|
+
"details": {
|
|
428
|
+
"agent": "orchestrator",
|
|
429
|
+
"description": "Direct database query for debugging",
|
|
430
|
+
"justification": "Investigating data sync issue #1234"
|
|
431
|
+
}
|
|
432
|
+
}
|
|
433
|
+
with open(audit_file, "a") as f:
|
|
434
|
+
f.write(json.dumps(entry) + "\n")
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
## 🧹 TTL Enforcement (Token Lifecycle)
|
|
438
|
+
|
|
439
|
+
Expired permission tokens are automatically tracked. Run periodic cleanup:
|
|
440
|
+
|
|
441
|
+
```bash
|
|
442
|
+
# List expired tokens (without removing)
|
|
443
|
+
python {baseDir}/scripts/revoke_token.py --list-expired
|
|
444
|
+
|
|
445
|
+
# Remove all expired tokens
|
|
446
|
+
python {baseDir}/scripts/revoke_token.py --cleanup
|
|
447
|
+
|
|
448
|
+
# Output:
|
|
449
|
+
# 🧹 TTL Cleanup Complete
|
|
450
|
+
# Removed: 3 expired token(s)
|
|
451
|
+
# Remaining active grants: 2
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
**Best Practice**: Run `--cleanup` at the start of each multi-agent task to ensure a clean permission state.
|
|
455
|
+
|
|
456
|
+
## ⚠️ Swarm Guard: Preventing Common Failures
|
|
457
|
+
|
|
458
|
+
Two critical issues can derail multi-agent swarms:
|
|
459
|
+
|
|
460
|
+
### 1. The Handoff Tax 💸
|
|
461
|
+
|
|
462
|
+
**Problem**: Agents waste tokens "talking about" work instead of doing it.
|
|
463
|
+
|
|
464
|
+
**Prevention**:
|
|
465
|
+
```bash
|
|
466
|
+
# Before each handoff, check your budget:
|
|
467
|
+
python {baseDir}/scripts/swarm_guard.py check-handoff --task-id "task_001"
|
|
468
|
+
|
|
469
|
+
# Output:
|
|
470
|
+
# 🟢 Task: task_001
|
|
471
|
+
# Handoffs: 1/3
|
|
472
|
+
# Remaining: 2
|
|
473
|
+
# Action Ratio: 100%
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
**Rules enforced**:
|
|
477
|
+
- **Max 3 handoffs per task** - After 3, produce output or abort
|
|
478
|
+
- **Max 500 chars per message** - Be concise: instruction + constraints + expected output
|
|
479
|
+
- **60% action ratio** - At least 60% of handoffs must produce artifacts
|
|
480
|
+
- **2-minute planning limit** - No output after 2min = timeout
|
|
481
|
+
|
|
482
|
+
```bash
|
|
483
|
+
# Record a handoff (with tax checking):
|
|
484
|
+
python {baseDir}/scripts/swarm_guard.py record-handoff \
|
|
485
|
+
--task-id "task_001" \
|
|
486
|
+
--from orchestrator \
|
|
487
|
+
--to data_analyst \
|
|
488
|
+
--message "Analyze sales data, output JSON summary" \
|
|
489
|
+
--artifact # Include if this handoff produces output
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
### 2. Silent Failure Detection 👻
|
|
493
|
+
|
|
494
|
+
**Problem**: One agent fails silently, others keep working on bad data.
|
|
495
|
+
|
|
496
|
+
**Prevention - Heartbeats**:
|
|
497
|
+
```bash
|
|
498
|
+
# Agents must send heartbeats while working:
|
|
499
|
+
python {baseDir}/scripts/swarm_guard.py heartbeat --agent data_analyst --task-id "task_001"
|
|
500
|
+
|
|
501
|
+
# Check if an agent is healthy:
|
|
502
|
+
python {baseDir}/scripts/swarm_guard.py health-check --agent data_analyst
|
|
503
|
+
|
|
504
|
+
# Output if healthy:
|
|
505
|
+
# 💚 Agent 'data_analyst' is HEALTHY
|
|
506
|
+
# Last seen: 15s ago
|
|
507
|
+
|
|
508
|
+
# Output if failed:
|
|
509
|
+
# 💔 Agent 'data_analyst' is UNHEALTHY
|
|
510
|
+
# Reason: STALE_HEARTBEAT
|
|
511
|
+
# → Do NOT use any pending results from this agent.
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
**Prevention - Result Validation**:
|
|
515
|
+
```bash
|
|
516
|
+
# Before using another agent's result, validate it:
|
|
517
|
+
python {baseDir}/scripts/swarm_guard.py validate-result \
|
|
518
|
+
--task-id "task_001" \
|
|
519
|
+
--agent data_analyst \
|
|
520
|
+
--result '{"status": "success", "output": {"revenue": 125000}, "confidence": 0.85}'
|
|
521
|
+
|
|
522
|
+
# Output:
|
|
523
|
+
# ✅ RESULT VALID
|
|
524
|
+
# → APPROVED - Result can be used by other agents
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
**Required result fields**: `status`, `output`, `confidence`
|
|
528
|
+
|
|
529
|
+
### Supervisor Review
|
|
530
|
+
|
|
531
|
+
Before finalizing any task, run supervisor review:
|
|
532
|
+
```bash
|
|
533
|
+
python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"
|
|
534
|
+
|
|
535
|
+
# Output:
|
|
536
|
+
# ✅ SUPERVISOR VERDICT: APPROVED
|
|
537
|
+
# Task: task_001
|
|
538
|
+
# Age: 1.5 minutes
|
|
539
|
+
# Handoffs: 2
|
|
540
|
+
# Artifacts: 2
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
**Verdicts**:
|
|
544
|
+
- `APPROVED` - Task healthy, results usable
|
|
545
|
+
- `WARNING` - Issues detected, review recommended
|
|
546
|
+
- `BLOCKED` - Critical failures, do NOT use results
|
|
547
|
+
|
|
548
|
+
## Troubleshooting
|
|
549
|
+
|
|
550
|
+
### Permission Denied
|
|
551
|
+
- Provide more specific justification (mention task, purpose, expected outcome)
|
|
552
|
+
- Narrow the requested scope
|
|
553
|
+
- Check agent trust level
|
|
554
|
+
|
|
555
|
+
### Blackboard Read Returns Null
|
|
556
|
+
- Entry may have expired (check TTL)
|
|
557
|
+
- Key may be misspelled
|
|
558
|
+
- Entry was never written
|
|
559
|
+
|
|
560
|
+
### Session Not Found
|
|
561
|
+
- Run `sessions_list` to see available sessions
|
|
562
|
+
- Session may need to be started first
|
|
563
|
+
|
|
564
|
+
## References
|
|
565
|
+
|
|
566
|
+
- [AuthGuardian Details](references/auth-guardian.md) - Full permission system documentation
|
|
567
|
+
- [Blackboard Schema](references/blackboard-schema.md) - Data structure specifications
|
|
568
|
+
- [Agent Trust Levels](references/trust-levels.md) - How trust is calculated
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Adapter Registry -- Routes agent requests to the correct adapter
|
|
3
|
+
*
|
|
4
|
+
* The registry is the single entry point the SwarmOrchestrator uses.
|
|
5
|
+
* It manages multiple adapters, routes requests based on agent ID patterns,
|
|
6
|
+
* and provides unified agent discovery across all registered adapters.
|
|
7
|
+
*
|
|
8
|
+
* @module AdapterRegistry
|
|
9
|
+
* @version 1.0.0
|
|
10
|
+
*/
|
|
11
|
+
import type { IAgentAdapter, AdapterConfig, AdapterRoute, RegistryConfig, AgentPayload, AgentContext, AgentResult, AgentInfo, AdapterEventHandler, AdapterEventType } from '../types/agent-adapter';
|
|
12
|
+
export declare class AdapterRegistry {
|
|
13
|
+
private adapters;
|
|
14
|
+
private routes;
|
|
15
|
+
private defaultAdapterName;
|
|
16
|
+
private eventHandlers;
|
|
17
|
+
private agentCache;
|
|
18
|
+
constructor(config?: RegistryConfig);
|
|
19
|
+
/**
|
|
20
|
+
* Register an adapter with the registry.
|
|
21
|
+
* Call this for each agent framework you want to support.
|
|
22
|
+
*/
|
|
23
|
+
registerAdapter(adapter: IAgentAdapter): void;
|
|
24
|
+
/**
|
|
25
|
+
* Initialize a registered adapter with its configuration
|
|
26
|
+
*/
|
|
27
|
+
initializeAdapter(adapterName: string, config?: AdapterConfig): Promise<void>;
|
|
28
|
+
/**
|
|
29
|
+
* Register + initialize in one call (convenience)
|
|
30
|
+
*/
|
|
31
|
+
addAdapter(adapter: IAgentAdapter, config?: AdapterConfig): Promise<void>;
|
|
32
|
+
/**
|
|
33
|
+
* Remove an adapter and shut it down
|
|
34
|
+
*/
|
|
35
|
+
removeAdapter(adapterName: string): Promise<void>;
|
|
36
|
+
/**
|
|
37
|
+
* Get a registered adapter by name
|
|
38
|
+
*/
|
|
39
|
+
getAdapter(adapterName: string): IAgentAdapter | undefined;
|
|
40
|
+
/**
|
|
41
|
+
* List all registered adapters
|
|
42
|
+
*/
|
|
43
|
+
listAdapters(): Array<{
|
|
44
|
+
name: string;
|
|
45
|
+
version: string;
|
|
46
|
+
ready: boolean;
|
|
47
|
+
}>;
|
|
48
|
+
/**
|
|
49
|
+
* Set the default adapter for unrouted requests
|
|
50
|
+
*/
|
|
51
|
+
setDefaultAdapter(adapterName: string): void;
|
|
52
|
+
/**
|
|
53
|
+
* Add a routing rule: agent IDs matching the pattern go to the specified adapter.
|
|
54
|
+
*
|
|
55
|
+
* Patterns:
|
|
56
|
+
* "lc:*" -> all agents prefixed with "lc:" go to the LangChain adapter
|
|
57
|
+
* "autogen:*" -> AutoGen agents
|
|
58
|
+
* "crew:*" -> CrewAI agents
|
|
59
|
+
* "*" -> catch-all
|
|
60
|
+
* "data_analyst" -> exact match
|
|
61
|
+
*/
|
|
62
|
+
addRoute(route: AdapterRoute): void;
|
|
63
|
+
/**
|
|
64
|
+
* Resolve which adapter should handle a given agent ID
|
|
65
|
+
*/
|
|
66
|
+
resolveAdapter(agentId: string): IAgentAdapter | null;
|
|
67
|
+
private matchPattern;
|
|
68
|
+
/**
|
|
69
|
+
* Execute an agent task, automatically routing to the correct adapter.
|
|
70
|
+
* This is the primary method the SwarmOrchestrator calls.
|
|
71
|
+
*/
|
|
72
|
+
executeAgent(agentId: string, payload: AgentPayload, context: AgentContext): Promise<AgentResult>;
|
|
73
|
+
/**
|
|
74
|
+
* Discover all agents across all registered adapters
|
|
75
|
+
*/
|
|
76
|
+
discoverAgents(): Promise<AgentInfo[]>;
|
|
77
|
+
/**
|
|
78
|
+
* Check if any adapter can handle a specific agent
|
|
79
|
+
*/
|
|
80
|
+
isAgentAvailable(agentId: string): Promise<boolean>;
|
|
81
|
+
healthCheck(): Promise<Record<string, {
|
|
82
|
+
healthy: boolean;
|
|
83
|
+
details?: string;
|
|
84
|
+
}>>;
|
|
85
|
+
on(event: AdapterEventType, handler: AdapterEventHandler): void;
|
|
86
|
+
off(event: AdapterEventType, handler: AdapterEventHandler): void;
|
|
87
|
+
private emit;
|
|
88
|
+
/**
|
|
89
|
+
* Shut down all adapters and clear the registry
|
|
90
|
+
*/
|
|
91
|
+
shutdownAll(): Promise<void>;
|
|
92
|
+
}
|
|
93
|
+
export declare function getRegistry(config?: RegistryConfig): AdapterRegistry;
|
|
94
|
+
//# sourceMappingURL=adapter-registry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"adapter-registry.d.ts","sourceRoot":"","sources":["../../adapters/adapter-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,SAAS,EAET,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAEhC,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,aAAa,CAA2D;IAChF,OAAO,CAAC,UAAU,CAAkC;gBAExC,MAAM,CAAC,EAAE,cAAc;IAWnC;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAQ7C;;OAEG;IACG,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IASvF;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnF;;OAEG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;;OAEG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI1D;;OAEG;IACH,YAAY,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAQxE;;OAEG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAW5C;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAMnC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IA8CrD,OAAO,CAAC,YAAY;IA0BpB;;;OAGG;IACG,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,WAAW,CAAC;IAyDvB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAqB5C;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBnD,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAqBpF,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAM/D,GAAG,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAKhE,OAAO,CAAC,IAAI;IAsBZ;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAanC;AAKD,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,eAAe,CAKpE"}
|