oabdelmaksoud langgraph-collab — Stateful Multi-Agent Graph Runner
Uses real LangGraph 0.6.11 StateGraph with shared state flowing through nodes.
Routes all LLM calls through openclaw agent --json — no API keys required.
Prerequisites (first run only)
~/.openclaw/skills/langgraph-collab/setup.sh
python3 ~/.openclaw/skills/langgraph-collab/build_agents.py --force
When to Use This vs. Other Skills
| Skill | Best for |
|---|---|
autogen-collab |
Open-ended debate, best answer wins |
crewai-collab |
Fixed pipeline with explicit expected outputs per task |
langgraph-collab |
Dynamic routing, supervisor delegation, conditional branching, parallel fan-out |
Topology Reference
| Topology | Structure | When to use |
|---|---|---|
linear |
A → B → C → END | Sequential pipeline, each output feeds next |
supervisor |
Supervisor ⇄ workers (dynamic) | Complex task, unknown sequence upfront |
parallel |
All workers run on same task (sequential fan-in) → synthesizer merges → END | Multiple expert perspectives on same task |
conditional |
Agent → condition check → branch A or B | If/else routing on metadata |
Available Agents
| ID | Role |
|---|---|
sage |
Solution Architect |
forge |
Implementation Engineer |
pixel |
Root Cause Analyst |
vista |
Business Analyst |
cipher |
Knowledge Curator |
vigil |
Quality Assurance Engineer |
anchor |
Content Specialist |
lens |
Multimodal Specialist |
main |
Cooper (orchestrator — use as supervisor) |
How to Invoke
1. Generate task ID
import uuid; task_id = str(uuid.uuid4())[:8]
2. Pick topology + agents
| Goal | Topology | Agents | Supervisor |
|---|---|---|---|
| Research → Design → Implement | linear |
vista,sage,forge |
— |
| Complex task, dynamic routing | supervisor |
sage,forge,pixel |
main |
| Multiple expert opinions + synthesis | parallel |
sage,pixel,vista |
cipher |
| Route on condition | conditional |
pixel,forge |
— |
3. Run (use exec background=true in OpenClaw)
~/.openclaw/skills/langgraph-collab/.venv/bin/python3 \
~/.openclaw/skills/langgraph-collab/langgraph_runner.py \
--topology supervisor \
--agents sage,forge,pixel \
--supervisor main \
--task "Design and implement a rate limiter for the trading engine" \
--task-id "<task-id>" \
--output /Users/omarabdelmaksoud/.openclaw/workspace/comms/langgraph/<task-id>/ \
--max-steps 10 \
--turn-timeout 90 \
--timeout 300
4. Poll for completion
cat /Users/omarabdelmaksoud/.openclaw/workspace/comms/langgraph/<task-id>/status.json
status: running → complete or error
5. Route result
cat /Users/omarabdelmaksoud/.openclaw/workspace/comms/langgraph/<task-id>/result.md
Route → Vigil quality gate → Omar via normal pipeline.
Output Files (always written, even on error)
| File | Contents |
|---|---|
status.json |
Run status |
result.md |
YAML frontmatter + final graph result |
transcript.md |
Per-node log, flushed immediately |
Conditional Topology
--condition "key=value:agent_true,agent_false"
Example — route on bug severity (Pixel sets metadata["severity"] in its response via METADATA: severity=high):
--topology conditional --agents pixel,forge,vigil \
--condition "severity=high:forge,vigil"
In v1, set metadata at launch with --metadata '{"key": "value"}'. Agents can also set metadata by writing METADATA: key=value on its own line in their response.
Example agent response:
I found a critical bug in the rate limiter.
METADATA: severity=high
Troubleshooting
Agent config not found: Run build_agents.py --force
LangGraph recursion error: Increase --max-steps (default 10)
Supervisor loops: Check that supervisor writes NEXT: FINISH — simplify the task or reduce --max-steps
Output dir exists: Use a new UUID
Slow runs: Each node is synchronous — budget turn-timeout × max-steps for total time