Content
**[中文文档](README_CN.md)**
# Multi-Agent Collaboration Protocol
> **LLM is the worker, not the coordinator. The brain (decision logic) and skeleton (workflow control) must be code.**
A universal, storage-agnostic protocol that enables multiple LLM agents to collaborate asynchronously through shared storage — with no direct communication, deterministic code-driven orchestration, and a strict 7-field data contract.
---
## Why This Exists
When you throw multiple LLM agents at a complex task, two approaches dominate:
| Approach | Problem |
|----------|---------|
| **Let LLMs self-coordinate** | Non-deterministic, prone to hallucination, no guarantee of consistency. Agents may forget, contradict, or deadlock. |
| **Hardcode a rigid pipeline** | Inflexible. Cannot adapt to task structure, parallel branches, or partial failures. |
This project takes a third path: **the LLM is the worker, code is the brain**. Agents observe, reason, and produce within bounded context. A Python orchestrator (`orchestrator.py`) handles validation, phase transitions, conflict arbitration, and state management — deterministically, every time.
---
## Core Architecture
### Three Roles
```
┌─────────────────────────────────────────────────────────────────────┐
│ Role Triangle │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Master (Worker) ──────── Output ────────→ Verifier (Checker) │
│ │ │ │
│ │ Verify ←──────── Feedback │ │
│ │ │ │
│ └────────── Monitor + Arbitrate ←────── Manager (Supervisor)│
│ │
│ Master produces → Verifier validates → Manager aggregates │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
| Role | Purpose | Core Action |
|------|---------|-------------|
| **Master** | Execute the work | Produce results → Create sub-tasks |
| **Verifier** | Validate independently | Verify → Feedback (confirmed / rejected / partially) |
| **Manager** | Monitor and merge | Monitor → Aggregate → Arbitrate → Merge |
### Key Design Principles
1. **No direct communication** — All interaction goes through shared storage. Agents never talk to each other.
2. **Code-driven orchestration** — `orchestrator.py` validates, normalizes, routes, and arbitrates. The LLM never decides flow control.
3. **Storage-agnostic** — Same protocol works with local JSON files or distributed MCP storage (Redis / MySQL / etc.).
4. **Multi-Master parallelism** — Multiple Masters can work simultaneously in pipeline, parallel, or distributed mode.
5. **Strict data contract** — Every record follows the same 7-field schema, validated before writing.
---
## The 7-Field Data Contract
Every record written to storage must conform to this contract (defined in `schemas/record.schema.json`):
```json
{
"id": "TASK_001", // Unique identifier
"who": "master_pentest_01", // Agent name (role_task_nodeId)
"time": 1719600000, // Unix timestamp (seconds)
"event": "task_completed", // Event type (17 defined types)
"what": "Scan completed", // One-sentence description
"detail": { // Context data (varies by event)
"result": "Found 3 vulnerabilities"
},
"trace": { // Traceability chain
"parent_id": null, // Parent task ID (null for root)
"session_id": "sess_1719600000" // Collaboration session
}
}
```
### Event Types
| Category | Events |
|----------|--------|
| **Task Lifecycle** | `task_started` · `task_pending` · `task_assigned` · `task_processing` · `task_completed` · `task_failed` · `task_blocked` · `task_retrying` · `task_merged` · `task_agent_lost` |
| **Health Check** | `heartbeat` · `checkpoint` |
| **Manager Events** | `summary` · `decision` · `protocol_violation` |
| **General** | `info` · `error` |
### Four Validation Gates
Records pass through four validation steps before being committed to storage:
```
Raw LLM output
│
▼
┌──────────────────┐
│ 1. JSON Repair │ ← Fix smart quotes, trailing commas, markdown fences
└──────────────────┘
│
▼
┌──────────────────┐
│ 2. Normalize │ ← Fill missing fields with safe defaults
└──────────────────┘
│
▼
┌──────────────────┐
│ 3. Validate │ ← Check 7-field contract + event type enum
└──────────────────┘
│
▼
┌──────────────────┐
│ 4. Schema Check │ ← JSON Schema validation (if jsonschema installed)
└──────────────────┘
│
▼
Committed to storage
```
---
## Work Cycle: READ → THINK → ACT → WRITE → LOOP
Every agent follows the same 5-step loop, but behavior differs by role:
```
┌─────────────────────────────────────────────────────────────────┐
│ Work Cycle │
│ │
│ ┌─────┐ ┌───────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │ READ│───→│THINK │───→│ ACT │───→│WRITE │───→│ LOOP │──┐ │
│ └─────┘ └───────┘ └──────┘ └──────┘ └──────┘ │ │
│ ▲ │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
| Phase | Master | Verifier | Manager |
|-------|--------|----------|---------|
| **READ** | Task requirements, shared knowledge, task queue | Task queue, parent task context | All records, heartbeats, anomalies |
| **THINK** | Can this be parallelized? Need sub-tasks? | Verification method? Branch task? | Anomalies? Need arbitration? Time to report? |
| **ACT** | Execute core business | Independently verify or execute branch | Write alerts, decisions, summaries |
| **WRITE** | Results + sub-tasks | Verification verdict | summary / decision / protocol_violation |
| **LOOP** | Update checkpoint → continue | Update checkpoint → continue | Update checkpoint → continue |
---
## Storage Modes
The protocol is identical regardless of storage backend. Only the read/write primitives differ.
### Mode A: Local Storage (Standalone)
Uses `scripts/orchestrator.py` with JSON files in `state/`. No MCP required, works offline.
```bash
# Initialize
python scripts/orchestrator.py init-state --task-space myproject -o state/myproject.json
# Write a record
python scripts/orchestrator.py normalize-record raw.json -o normalized.json
python scripts/orchestrator.py validate-record normalized.json
python scripts/orchestrator.py add-record --state state/myproject.json --record normalized.json
# Read records (supports incremental)
python scripts/orchestrator.py read-records --state state/myproject.json --limit 20
python scripts/orchestrator.py read-records --state state/myproject.json --since 1719600000
# Manager operations
python scripts/orchestrator.py generate-summary --state state/myproject.json -o summary.json
python scripts/orchestrator.py detect-anomalies --state state/myproject.json
python scripts/orchestrator.py arbitrate --state state/myproject.json
python scripts/orchestrator.py merge-outputs --state state/myproject.json -o merge.json
python scripts/orchestrator.py merge-outputs --state state/myproject.json --dry-run # preview
python scripts/orchestrator.py merge-outputs --state state/myproject.json --force # force
```
### Mode B: MCP Storage (Distributed)
Uses MCP tools (`write_record`, `read_records`, `list_tasks`, `create_task_space`) backed by Redis / MySQL / etc.
```python
# Write a record (still normalize + validate first)
write_record(normalized_record)
# Read records
read_records(filter_who=None, filter_event=None, limit=20)
# Heartbeat
write_record({event: "heartbeat", who: "master_proj_01", ...})
# Manager operations
read_records(filter_event="summary") # aggregation
read_records(filter_event="heartbeat") # health monitoring
```
> **⚠️ Performance Note**: MCP `read_records` does not support server-side time filtering. Every incremental check performs a full scan + client-side filter. This is fine for small-to-medium workloads but may degrade at scale. For high-volume scenarios, prefer Local mode (native `--since` support) or add server-side filtering to your MCP backend.
---
## Reliability Mechanisms
### 1. Heartbeat Protocol
Each agent writes a `heartbeat` event every **2 minutes** during active work. The Manager monitors these — if no heartbeat for **5 minutes**, it writes a `task_agent_lost` event and awaits human intervention.
```json
{
"id": "HB_1719600500",
"who": "master_pentest_01",
"time": 1719600500,
"event": "heartbeat",
"what": "Heartbeat: master alive",
"detail": {
"current_task": "TASK_001",
"status": "executing",
"progress": "60% complete"
},
"trace": { "parent_id": null, "session_id": "sess_001" }
}
```
> **Note**: LLM agents operate in request-response mode and cannot self-schedule. Heartbeats depend on external triggers (e.g., `/loop` in Claude Code, cron jobs, or user interaction). Recommended intervals: Master/Verifier 5–10 min, Manager 2–5 min.
### 2. Retry Strategy
When a task fails, agents automatically retry before escalating:
| Attempt | Wait | Action |
|---------|------|--------|
| Original | — | Execute task |
| Retry 1 | ~30s | Write `task_retrying` event |
| Retry 2 | ~60s | Write `task_retrying` event |
| Max retries exceeded | — | Escalate to `task_blocked` with `requires_human_intervention: true` |
**Do NOT retry** on: schema validation errors, logical errors, permission denied, or any deterministic failure.
### 3. Incremental Check Protocol
Agents persist a `last_check_time` checkpoint. On each awakening, they only read records with `time > last_check_time`:
```
Full scan: O(total records) — read everything every time
Incremental: O(new records) — only read what changed ← preferred
```
Checkpoints are stored as dedicated `checkpoint` events (not mixed into `info` records) for clean separation of concerns.
### 4. Atomic Writes and File Locking
- **`atomic_write_text`**: Writes to a temp file, then `os.replace()` for atomic commit — prevents state corruption from interrupted writes.
- **`state_lock`**: Advisory file lock with PID tracking and stale lock detection (5 min timeout) — prevents concurrent read-modify-write races.
### 5. JSON Repair
LLMs frequently produce malformed JSON. The bundled `json_repair.py` handles:
| Issue | Fix |
|-------|-----|
| Smart quotes (`""` `''`) | Replace with ASCII quotes |
| Markdown code fences (` ```json `) | Strip fences |
| Trailing commas before `}` / `]` | Remove |
| Unbalanced brackets | Extract innermost balanced object |
---
## Multi-Master Architecture
Multiple Master nodes can work in parallel, each with their own private workspace:
### Pipeline Mode (Different Phases)
```
Master_01: Phase 1 → Master_02: Phase 2 → Master_03: Phase 3
```
### Parallel Mode (Different Branches)
```
Master_01: Branch A ─┐
├→ Manager: Aggregate
Master_02: Branch B ─┘
```
### Distributed Mode (Different Tasks)
```
Master_01: Task X → Master_02: Task Y → Manager: Aggregate
```
Masters never communicate directly. They coordinate through shared storage, and the Manager handles aggregation and conflict resolution.
---
## Merge & Conflict Resolution
When all tasks complete, the Manager merges Master outputs into a final deliverable:
### Pre-merge Checks
- ✅ All Master tasks have `task_completed` events
- ✅ No outstanding `task_failed` / `task_blocked` without resolution
- ✅ No tasks still in `task_processing`
### Content-Level Resolution
The orchestrator performs three types of content analysis across Master outputs:
| Detection | Condition | Resolution |
|-----------|-----------|------------|
| **Identical** | Same `detail.result` text | Deduplicate; prefer verified-as-`confirmed` |
| **Conflicting** | Same task prefix, different results | Prefer verified-as-`confirmed`; fall back to latest timestamp |
| **Overlapping** | One result is a substring of another | Keep the more complete (longer) version |
### Merge Output Example
```json
{
"id": "MERGE_1719600600",
"event": "task_merged",
"detail": {
"source_tasks": ["TASK_001", "TASK_002"],
"verification_status": {"TASK_001": "confirmed", "TASK_002": "unverified"},
"overlaps": [
{"tasks": ["TASK_001", "TASK_002"], "type": "identical", "kept": "TASK_001"}
],
"conflicts": [],
"merge_order": ["TASK_001"],
"deduped_from": ["TASK_002"],
"status": "delivered"
}
}
```
---
## Workspace Isolation
| Zone | Purpose | Master | Verifier | Manager |
|------|---------|--------|----------|---------|
| Private workspace | Exclusive read/write | ✅ Own only | ✅ Own only | ❌ |
| Summary zone | Aggregated reports | ❌ | ❌ | ✅ Write only |
| Shared knowledge | Input data | ✅ Read only | ✅ Read only | ✅ Read only |
| Task queue | Pending/processing/done | ✅ Read/Write | ✅ Read | ✅ Read |
**Hard constraint**: No agent may write to another agent's private workspace. Violations are detected and reported as `protocol_violation` events.
---
## Quick Start
### Prerequisites
- Python 3.8+
- (Optional) `jsonschema>=4.20` for full JSON Schema validation
### 1. Install Dependencies
```bash
pip install -r requirements.txt # Optional: only jsonschema
```
### 2. Create a Task Space
```bash
python scripts/orchestrator.py create-task-space myproject_20260702
```
### 3. Initialize State
```bash
python scripts/orchestrator.py init-state --task-space myproject -o state/myproject.json
```
### 4. Run the Self-Test
```bash
python scripts/self_test.py
```
### 5. Validate Project Structure
```bash
python scripts/validate_structure.py
```
---
## Project Structure
```
multi-agent-collab/
├── SKILL.md # Protocol specification (Claude Code skill)
├── README.md # This file
├── requirements.txt # Python dependencies
│
├── schemas/
│ └── record.schema.json # 7-field data contract (JSON Schema)
│
├── prompts/
│ ├── master-workflow.md # Master role prompt
│ ├── verifier-workflow.md # Verifier role prompt
│ └── manager-workflow.md # Manager role prompt
│
├── scripts/
│ ├── orchestrator.py # Deterministic orchestration engine
│ ├── json_repair.py # LLM JSON output repair utility
│ ├── self_test.py # Self-test suite
│ └── validate_structure.py # Project structure validation
│
└── state/
└── example.json # Example state file
```
---
## Orchestrator Command Reference
| Command | Description |
|---------|-------------|
| `init-state` | Initialize a new collaboration state |
| `validate-record` | Validate a record against the 7-field contract + JSON Schema |
| `normalize-record` | Fill missing fields with safe defaults |
| `repair-json` | Repair malformed JSON (smart quotes, fences, trailing commas) |
| `add-record` | Add a validated record to state (with file locking) |
| `read-records` | Read records with filtering and incremental support |
| `generate-summary` | Generate a global status report |
| `detect-anomalies` | Detect format errors, timeouts, protocol violations |
| `arbitrate` | Resolve conflicting records (latest timestamp wins) |
| `merge-outputs` | Merge completed Master outputs with dedup and conflict resolution |
| `list-tasks` | List available task spaces |
| `create-task-space` | Create a new task space |
| `check-status` | Check collaboration status (phase, agents, summary) |
---
## Use Cases
### Penetration Testing
- **Master_01**: Network scan → **Verifier_01**: Validate findings → **Manager**: Merge report
### Code Review
- **Master_01**: Main review → **Verifier_01**: Generate unit tests → **Manager**: Aggregate feedback
### Research
- **Master_01**: Primary research → **Master_02**: Literature survey → **Verifier_01**: Cross-check claims → **Manager**: Synthesize report
### Any Parallel Workflow
- Split work across Masters, validate with Verifiers, aggregate with Manager
---
## Design Decisions
### Why shared storage, not direct messaging?
Direct LLM-to-LLM communication is non-deterministic and unobservable. Shared storage provides:
- **Auditability**: Every interaction is a persisted record with a timestamp
- **Decoupling**: Agents don't need to know about each other
- **Resumability**: Any agent can be restarted and catch up via incremental reads
### Why code-driven orchestration, not prompt-driven?
Prompts are suggestions, not guarantees. An LLM might:
- Skip validation and write malformed records
- Forget to check for conflicts before writing
- Invent new event types that break downstream consumers
`orchestrator.py` enforces these mechanically. The LLM focuses on what it's good at — reasoning within bounded context and producing structured output.
### Why a 7-field contract?
A fixed schema with a small number of well-defined fields:
- Makes validation trivial and fast
- Prevents schema drift across agents
- Enables generic tooling (aggregate, arbitrate, merge) that works for any domain
### Why separate Verifier from Master?
Independent verification catches errors that self-review cannot. The Verifier must not trust the Master's claims — it applies its own methodology and reports what it actually found.
---
Connection Info
You Might Also Like
No recommendations available