oabdelmaksoud autogen-collab — Multi-Agent Debate Runner
Routes all LLM calls through openclaw agent --json — uses your existing
provider configuration transparently. No API keys, no venv, no .env file needed.
Prerequisites (first run only)
python3 ~/.openclaw/skills/autogen-collab/build_personas.py --force
Run once after setup or after updating any agent's SOUL.md. The runner auto-rebuilds stale configs on each invocation, but the agents directory must exist.
When Cooper Should Use This
Auto-trigger (check before delegating normally)
- Task type is
architecture,design,rca, orresearchAND complexity ishigh - Task is tagged
[autogen]by Omar - Omar says "debate this", "get consensus", or "ask the team"
- Cooper's confidence on the right approach is below 70%
Do NOT use for
- Simple, well-defined implementation tasks → delegate to Forge directly
- Tasks with a single clear owner (e.g. "write a blog post" → Anchor)
- Quick lookups or factual questions
How to Invoke
1. Generate a task ID
import uuid
task_id = str(uuid.uuid4())[:8] # e.g. "a3f9b1c2"
2. Choose agents by task type
| Task type | Agents |
|---|---|
architecture / design |
sage,forge,pixel |
research / analysis |
vista,cipher,lens |
debug / rca |
pixel,forge,sage |
content / delivery |
anchor,cipher,vigil |
| Custom | specify explicitly |
3. Run the debate
python3 ~/.openclaw/skills/autogen-collab/autogen_runner.py \
--mode debate \
--agents sage,pixel \
--task "Your task here" \
--task-id "<task-id>" \
--output /Users/omarabdelmaksoud/.openclaw/workspace/comms/autogen/<task-id>/ \
--max-rounds 10 \
--turn-timeout 60 \
--timeout 300
Use OpenClaw's exec tool with background=true so Cooper doesn't block.
Flags:
--max-rounds— max total agent turns (default: 10)--turn-timeout— per-turn timeout in seconds (default: 60)--timeout— total wall-clock timeout in seconds (default: 300)
4. Poll for completion
Every 15 seconds:
cat /Users/omarabdelmaksoud/.openclaw/workspace/comms/autogen/<task-id>/status.json
Continue when status is complete, timeout, or error (not running).
5. Read and route result
cat /Users/omarabdelmaksoud/.openclaw/workspace/comms/autogen/<task-id>/result.md
- Write result to the relevant agent outbox (
comms/outboxes/<agent>.md) - Send to Vigil for quality scoring (
comms/inboxes/vigil.md) - After Vigil approves (score ≥ 3), deliver to Omar
6. Log in TASKS.json
{
"autogen_session": "<task-id>",
"transcript": "comms/autogen/<task-id>/transcript.md",
"status": "complete"
}
Output Files
| File | Contents |
|---|---|
status.json |
Run status: running, complete, timeout, error |
result.md |
Final answer with YAML frontmatter (task_id, agents, rounds, consensus_reached, duration_seconds) |
transcript.md |
Full conversation log, flushed per turn |
Status and result are always written, even on failure — Cooper can always check status.json.
How Consensus Works
Agents receive the full conversation history each turn. When an agent genuinely
agrees with the previous response, it writes ##AGREED## alone on a new line.
The runner detects this and ends the debate immediately.
If no consensus is reached within --max-rounds or --timeout, the runner
synthesizes the last 40 lines of transcript into result.md with
consensus_reached: false.
Troubleshooting
Agent turn times out: Increase --turn-timeout or try a faster model agent.
Check if the agent's provider is responsive with openclaw agent --agent <id> --message "ping" --json
Output dir already exists: Another run used the same task ID. Generate a new UUID.
Debate ends without consensus: Check transcript.md — reduce --max-rounds,
simplify the task, or pick agents with closer domain alignment.
Runner crashes before writing output: Should not happen — status.json is written
immediately on startup. If it does, check that openclaw CLI is in PATH.