{
  "schemaVersion": "1.0",
  "item": {
    "slug": "parallel-agents",
    "name": "Parallel Agents",
    "source": "tencent",
    "type": "skill",
    "category": "效率提升",
    "sourceUrl": "https://clawhub.ai/jdalbright/parallel-agents",
    "canonicalUrl": "https://clawhub.ai/jdalbright/parallel-agents",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/parallel-agents",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=parallel-agents",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "USAGE-GUIDE.md",
      "ai_orchestrator.py",
      "examples/README.md",
      "examples/simple_parallel_research.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "slug": "parallel-agents",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T20:21:50.968Z",
      "expiresAt": "2026-05-07T20:21:50.968Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=parallel-agents",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=parallel-agents",
        "contentDisposition": "attachment; filename=\"parallel-agents-3.2.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "parallel-agents"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/parallel-agents"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/parallel-agents",
    "agentPageUrl": "https://openagent3.xyz/skills/parallel-agents/agent",
    "manifestUrl": "https://openagent3.xyz/skills/parallel-agents/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/parallel-agents/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Parallel Agents Skill - REAL AI Edition",
        "body": "🚀 Execute tasks with ACTUAL AI-powered parallel agents using OpenClaw's sessions_spawn.\n\n⚠️ HONEST STATUS: This skill has been rewritten to use REAL AI via sessions_spawn.\nPreviously it simulated agents with templates. Now it ACTUALLY spawns AI sub-sessions."
      },
      {
        "title": "🚨 CRITICAL USAGE NOTE",
        "body": "The orchestrator MUST be called from within an OpenClaw agent session, NOT as a standalone script.\n\nWhy? The tools module (which provides sessions_spawn) is only available in the agent's runtime context, not in subprocess/exec calls.\n\n✅ CORRECT: Call sessions_spawn directly from agent code (see USAGE-GUIDE.md)\n❌ INCORRECT: Run orchestrator as standalone Python script via exec/subprocess\n\n📖 SEE: USAGE-GUIDE.md for tested working examples and patterns"
      },
      {
        "title": "🎯 Capabilities",
        "body": "This skill provides 4 levels of agent automation:\n\nLevelFeatureWhat It Does1Task Agents (16 types)Specialized agents for content, dev, QA, docs2Meta Agents (4 types)Agents that create, review, refine, and orchestrate other agents3Iterative RefinementAutomatic quality improvement loop (Creator → Reviewer → Refiner)4Agent OrchestratorFully autonomous workflow management - just ask and it handles everything\n\nProven Capabilities:\n\n✅ 20 concurrent agents spawned simultaneously\n✅ Smart model hierarchy - Haiku → Kimi → Opus (cost optimization)\n✅ Auto-escalation - Agents automatically use better models if needed\n✅ 100% success rate on mass creation tests with hierarchy\n✅ 3/3 agents refined to 8.5+ quality in single iteration\n✅ 4-agent hierarchy for complete autonomy"
      },
      {
        "title": "What This Actually Does",
        "body": "This skill creates real AI sub-sessions using OpenClaw's sessions_spawn tool. Each \"agent\" is:\n\nA spawned OpenClaw session (not a subprocess)\nRunning real AI (same model as the host)\nCompletely isolated from other agents\nAble to use all the same tools as the host\n\nPrevious version: Subprocess workers with templates ❌\nCurrent version: Real spawned AI sessions ✅"
      },
      {
        "title": "Requirements",
        "body": "Must be run inside an OpenClaw session (for sessions_spawn access)\nOpenClaw gateway must be running\nThe sessions tool must be available in your environment"
      },
      {
        "title": "✅ Correct Usage: Direct sessions_spawn Calls",
        "body": "From within an OpenClaw agent (like Scout):\n\n# Spawn multiple agents in parallel using sessions_spawn tool directly\nfrom tools import sessions_spawn\n\n# Agent 1: Research task\nresult1 = sessions_spawn(\n    task=\"Research and provide: Top 3 gay-friendly bars in Savannah. Return as JSON.\",\n    runTimeoutSeconds=90,\n    cleanup=\"delete\"\n)\n\n# Agent 2: Different research task  \nresult2 = sessions_spawn(\n    task=\"Research and provide: Best restaurants for birthday dinner. Return as JSON.\",\n    runTimeoutSeconds=90,\n    cleanup=\"delete\"\n)\n\n# Agent 3: Another parallel task\nresult3 = sessions_spawn(\n    task=\"Research and provide: Top photo spots in Savannah. Return as JSON.\",\n    runTimeoutSeconds=90,\n    cleanup=\"delete\"\n)\n\n# All 3 agents now running in parallel!\n# Check results with sessions_list() and sessions_history()"
      },
      {
        "title": "❌ Incorrect Usage: Standalone Script",
        "body": "# This WON'T work - tools module not available in subprocess\npython3 ~/.openclaw/skills/parallel-agents/ai_orchestrator.py"
      },
      {
        "title": "Basic Usage",
        "body": "from ai_orchestrator import RealAIParallelOrchestrator, AgentTask\n\n# Create orchestrator\norch = RealAIParallelOrchestrator(max_concurrent=5)\n\n# Define tasks\ntasks = [\n    AgentTask(\n        agent_type='content_writer_funny',\n        task_description='Write a caption about gym life',\n        input_data={'tone': 'motivational'}\n    ),\n    AgentTask(\n        agent_type='content_writer_creative',\n        task_description='Write a caption about gym life',\n        input_data={'tone': 'inspirational'}\n    ),\n]\n\n# Execute in parallel (ACTUALLY spawns AI sessions)\nresults = orch.run_parallel(tasks)"
      },
      {
        "title": "How It Works",
        "body": "┌─────────────────────────────────────────────────────────┐\n│                    Main Session                         │\n│              (Your OpenClaw Instance)                   │\n│                      🧠 Host AI                         │\n└─────────────────────┬───────────────────────────────────┘\n                      │ sessions_spawn (REAL)\n                      │\n        ┌─────────────┼─────────────┬─────────────┐\n        │             │             │             │\n   ┌────▼────┐   ┌────▼────┐   ┌────▼────┐   ┌────▼────┐\n   │ Agent 1 │   │ Agent 2 │   │ Agent 3 │   │ Agent N │\n   │   📝    │   │   💻    │   │   🔍    │   │   🎨    │\n   │ REAL AI │   │ REAL AI │   │ REAL AI │   │ REAL AI │\n   │ Session │   │ Session │   │ Session │   │ Session │\n   └─────────┘   └─────────┘   └─────────┘   └─────────┘"
      },
      {
        "title": "The sessions_spawn Integration",
        "body": "Each agent is spawned with:\n\nfrom tools import sessions_spawn\n\nresult = sessions_spawn(\n    task=agent_prompt,           # Full task description\n    agent_id=f\"agent_{type}_{id}\",  # Unique identifier\n    model=\"kimi-coding/k2p5\",     # AI model\n    runTimeoutSeconds=120,        # Max execution time\n    cleanup=\"delete\"              # Auto-cleanup\n)"
      },
      {
        "title": "Content Writers",
        "body": "Agent TypePurposeSystem Promptcontent_writer_creativeImaginative, artisticRich metaphors, emotional resonancecontent_writer_funnyHumorous, wittyJokes, wordplay, relatable humorcontent_writer_educationalTeaching contentClear explanations, actionable takeawayscontent_writer_trendyViral contentTrend-aware, culturally relevantcontent_writer_controversialDebate-sparkingHot takes, respectful discourse"
      },
      {
        "title": "Development Agents",
        "body": "Agent TypePurposeOutputfrontend_developerReact/Vue/AngularComponent structure, state managementbackend_developerFastAPI/Flask/DjangoAPI endpoints, auth, modelsdatabase_architectSchema designTables, indexes, migrationsapi_designerREST/GraphQLOpenAPI specs, rate limitsdevops_engineerCI/CDDocker, K8s, pipelines"
      },
      {
        "title": "QA Agents",
        "body": "Agent TypePurposeFocuscode_reviewerQuality reviewBest practices, maintainabilitysecurity_reviewerSecurity scanVulnerabilities, threatsperformance_reviewerOptimizationBottlenecks, complexityaccessibility_reviewerWCAG complianceA11y, screen readerstest_engineerTest coverageUnit/integration tests"
      },
      {
        "title": "Documentation",
        "body": "Agent TypePurposedocumentation_writerREADMEs, API docs, guides"
      },
      {
        "title": "Personalized Agents (Jake's Suite) 🐾",
        "body": "Agents created specifically for Jake's needs via agent_orchestrator research:\n\nAgent TypePurposeKey Featurestravel_event_plannerTrip content coordinationSavannah/Atlanta/SD Pride planning, gear checklists, event schedulesdonut_care_coordinatorPrincess Donut managementFeeding tracking, vet reminders, pet sitter coordination, daily updatespup_community_engagerPup community managementBluesky/Twitter monitoring, DM triage, authentic pup voice engagementprint_project_manager3D printing workflowModel queue, filament tracking, vibecoding integration, print optimizationtraining_assistantAlmac work productivityTraining prep, onboarding, session checklists, material templates\n\nTotal Agent Types: 25\n\n5 Content Writers\n5 Development Agents\n5 QA Agents\n1 Documentation Agent\n5 Personalized Agents 🆕\n4 Meta Agents"
      },
      {
        "title": "Meta Agents 🔄 (Agent Creation System)",
        "body": "Agent TypePurposeWhat It Doesagent_creatorDesigns new AI agentsCreates complete agent definitions with prompts, schemas, examplesagent_design_reviewerValidates agent designsReviews quality, completeness, production readiness (scores 0-10)agent_refinerImproves agent designsApplies fixes based on review feedback to reach target scoresagent_orchestratorMaster coordinatorPlans workflows, spawns agents, coordinates execution, compiles results\n\nThe 4-Agent Hierarchy:\n\nLevel 4: USER\n    ↓ asks\nLevel 3: AGENT_ORCHESTRATOR\n    ↓ plans, spawns, coordinates\nLevel 2: Meta Agents (creator, reviewer, refiner)\n    ↓ designs, reviews, refines\nLevel 1: Task Agents (content writers, developers, QA)\n    ↓ does work\nLevel 0: Actual Tasks\n\nTotal Agent Types: 20\n\n5 Content Writers\n5 Development Agents\n5 QA Agents\n1 Documentation Agent\n4 Meta Agents 🆕\n\nWorkflow 1: Simple Creation (2 agents)\n\nfrom ai_orchestrator import (\n    RealAIParallelOrchestrator,\n    create_meta_agent_workflow\n)\n\norch = RealAIParallelOrchestrator()\n\n# Define agents to create\nnew_agents = [\n    {'name': 'crypto_analyst', 'purpose': 'Analyze crypto trends'},\n    {'name': 'content_strategist', 'purpose': 'Plan content calendars'}\n]\n\n# Creates: 2 creators + 2 reviewers (4 tasks)\ntasks = create_meta_agent_workflow(new_agents)\nresults = orch.run_parallel(tasks)\n\nWorkflow 2: Iterative Refinement (3-agent loop)\n\n# The full 3-agent refinement workflow:\n# Creator → Reviewer (scores) → Refiner (fixes) → Reviewer (verifies)\n# Repeats until score >= 8.5\n\nagents_to_refine = [\n    {'name': 'my_agent', 'current_score': 7.4, 'target': 8.5}\n]\n\n# This runs the full loop automatically\nresults = orch.run_iterative_refinement(agents_to_refine)\n# Result: 7.4 → 8.5+ ✅\n\nWorkflow 3: Orchestrated Mass Creation (autonomous)\n\n# Spawn the orchestrator to handle everything:\n# - Plans workflow\n# - Spawns all agents\n# - Coordinates execution\n# - Handles refinements\n# - Compiles final report\n\nresult = sessions_spawn(\n    task=\"Create 5 new agents and ensure all score 8.5+\",\n    agent_type='agent_orchestrator',\n    timeout=600\n)\n\n# The orchestrator does everything autonomously!\n\nThis enables agent bootstrapping - the system creates and improves itself!"
      },
      {
        "title": "AgentTask",
        "body": "@dataclass\nclass AgentTask:\n    agent_type: str           # Type from registry (required)\n    task_description: str     # What to do (required)\n    input_data: Dict          # Input parameters (optional)\n    task_id: str             # Unique ID (auto-generated)\n    timeout_seconds: int     # Max time (default: 120)\n    output_format: str       # json|markdown|code|text"
      },
      {
        "title": "AgentResult",
        "body": "@dataclass\nclass AgentResult:\n    task_id: str             # Matches AgentTask\n    agent_type: str          # Agent that produced this\n    status: str              # pending|running|completed|failed\n    output: Any              # Generated content (agent-dependent format)\n    execution_time: float    # Time taken\n    error: str              # Error message if failed\n    session_key: str        # Spawned session identifier"
      },
      {
        "title": "Example 1: Generate Multiple Content Styles",
        "body": "from ai_orchestrator import RealAIParallelOrchestrator, create_content_team\n\norch = RealAIParallelOrchestrator(max_concurrent=5)\ntasks = create_content_team(\"Monday motivation\", platform=\"bluesky\")\n\n# This spawns 5 REAL AI agents\nresults = orch.run_parallel(tasks)\n\nprint(\"Agents spawned! Each is generating content...\")\nprint(\"Check sessions_list() to see running agents\")"
      },
      {
        "title": "Example 2: Full-Stack Development Team",
        "body": "from ai_orchestrator import RealAIParallelOrchestrator, create_dev_team\n\norch = RealAIParallelOrchestrator(max_concurrent=5)\ntasks = create_dev_team(\"TaskManager\", ['auth', 'tasks', 'teams'])\n\n# Spawns 5 dev agents in parallel\nresults = orch.run_parallel(tasks)\n\n# Each agent designs their layer independently\n# - Frontend agent designs React components\n# - Backend agent designs FastAPI routes\n# - Database agent designs schema\n# - etc."
      },
      {
        "title": "Example 3: Code Review Team",
        "body": "from ai_orchestrator import RealAIParallelOrchestrator, create_review_team\n\ncode = open('app.py').read()\n\norch = RealAIParallelOrchestrator(max_concurrent=5)\ntasks = create_review_team(code)\n\n# Spawns 5 reviewers simultaneously\nresults = orch.run_parallel(tasks)\n\n# Each reviews from different angle:\n# - Code quality\n# - Security\n# - Performance\n# - Accessibility\n# - Test coverage"
      },
      {
        "title": "Example 4: Meta-Agent System (Agents Creating Agents) 🔄",
        "body": "from ai_orchestrator import (\n    RealAIParallelOrchestrator,\n    create_meta_agent_workflow\n)\n\norch = RealAIParallelOrchestrator(max_concurrent=6)\n\n# Define new agents to create\nnew_agents = [\n    {\n        'name': 'social_media_analyst',\n        'purpose': 'Analyze social media performance',\n        'domain': 'social media analytics',\n        'capabilities': ['engagement analysis', 'trend identification']\n    },\n    {\n        'name': 'bug_hunter',\n        'purpose': 'Find bugs in code',\n        'domain': 'software QA',\n        'capabilities': ['static analysis', 'edge case detection']\n    },\n    {\n        'name': 'api_documenter',\n        'purpose': 'Generate API docs',\n        'domain': 'technical writing',\n        'capabilities': ['endpoint extraction', 'example generation']\n    }\n]\n\n# Creates 6 tasks: 3 creators + 3 reviewers\ntasks = create_meta_agent_workflow(new_agents)\nresults = orch.run_parallel(tasks)\n\n# Result: 3 complete agent definitions + 3 quality reviews\n# All created entirely by AI in parallel!\n\nThis is agent bootstrapping - the system creates itself!"
      },
      {
        "title": "Example 5: Mass Agent Creation (10+ Agents at Once) 🔥",
        "body": "Proven Capability: The system has been tested with 20 concurrent agents (10 creators + 10 reviewers) all spawned simultaneously.\n\nfrom ai_orchestrator import RealAIParallelOrchestrator, AgentTask\n\norch = RealAIParallelOrchestrator(max_concurrent=10)\n\n# Define 10 new agents to create\nnew_agents = [\n    {'name': 'engagement_optimizer', 'purpose': 'Analyze social media posts', \n     'domain': 'social media', 'capabilities': ['analytics', 'optimization']},\n    {'name': 'workout_designer', 'purpose': 'Create gym/home workouts',\n     'domain': 'fitness', 'capabilities': ['program design', 'adaptation']},\n    {'name': 'email_drafter', 'purpose': 'Write professional/personal emails',\n     'domain': 'communication', 'capabilities': ['tone adaptation', 'drafting']},\n    # ... more agents\n]\n\n# Create all 10 agents + 10 reviewers = 20 parallel agents!\nall_tasks = []\nfor agent in new_agents:\n    # Add creator\n    all_tasks.append(AgentTask(\n        agent_type='agent_creator',\n        task_description=f\"Design agent: {agent['name']}\",\n        input_data=agent,\n        timeout_seconds=180\n    ))\n    # Add reviewer\n    all_tasks.append(AgentTask(\n        agent_type='agent_design_reviewer',\n        task_description=f\"Review {agent['name']}\",\n        input_data={'agent_name': agent['name']},\n        timeout_seconds=120\n    ))\n\n# SPAWN 20 AGENTS SIMULTANEOUSLY\nresults = orch.run_parallel(all_tasks)\n\nReal-World Results (2026-02-08 Test):\n\n✅ 10 Agent Creators spawned successfully\n✅ 10 Design Reviewers spawned successfully\n✅ All 20 completed without errors\n✅ Average quality score: 8.1/10\n✅ Production-ready agent definitions created\n\nPractical Limit: ~20-50 concurrent agents (depends on system resources)\n\nSee: examples/mass_agent_creation.py for full implementation."
      },
      {
        "title": "Collecting Results",
        "body": "Agents return their output in their session transcript. To collect:\n\n# After spawning, poll for results\nfrom tools import sessions_list, sessions_history\n\n# Check which agents have completed\nsessions = sessions_list(agent_id_pattern=\"agent_*\")\n\nfor session in sessions:\n    if session['status'] == 'completed':\n        history = sessions_history(session['sessionKey'])\n        # Parse JSON from final assistant message\n        output = json.loads(history[-1]['content'])\n\nNote: Full result collection is implemented in the orchestrator.\nResults are available via results attribute after spawning."
      },
      {
        "title": "Why sessions_spawn?",
        "body": "Previous implementations tried:\n\nThreading - Limited by Python GIL, not truly parallel\nMultiprocessing - macOS spawn issues, complex IPC\nSubprocess workers - Templates, not real AI\n\nsessions_spawn is the solution:\n\nTrue isolation (separate sessions)\nFull AI capabilities (same model)\nBuilt into OpenClaw\nAutomatic cleanup"
      },
      {
        "title": "Limitations",
        "body": "OpenClaw dependency - Must run inside OpenClaw session\nResult collection - Requires polling sessions_list\nCost - Each spawn = separate API call (but same model/credentials)\nTimeout - Agents limited to 120 seconds by default"
      },
      {
        "title": "File Structure",
        "body": "~/.openclaw/skills/parallel-agents/\n├── README.md                          # Quick start guide\n├── SKILL.md                           # Complete documentation\n├── USAGE-GUIDE.md                     # Practical examples and patterns\n├── ai_orchestrator.py                 # Core orchestrator code\n├── helpers.py                         # Auto-retry helper functions\n└── examples/                          # Working examples\n    ├── README.md                      # Examples documentation\n    └── simple_parallel_research.py    # Simple example"
      },
      {
        "title": "Version History",
        "body": "3.2.0 (2026-02-08): SMART MODEL HIERARCHY\n\n✅ Added intelligent model escalation (Haiku → Kimi → Opus)\n✅ Cost optimization: Try cheapest model first, escalate if needed\n✅ Updated helpers.py with spawn_with_model_hierarchy()\n✅ Auto-escalation in spawn_with_retry() and spawn_parallel_with_retry()\n✅ Comprehensive docs on model selection and cost savings\n✅ Tested: Haiku completes simple tasks successfully\n\n\n\n3.1.0 (2026-02-08): PRODUCTION READY\n\n✅ Added auto-retry helpers (spawn_with_retry, spawn_parallel_with_retry)\n✅ Cleaned up development artifacts (removed 18 outdated files)\n✅ Added comprehensive documentation (README, USAGE-GUIDE)\n✅ Simplified examples (one clear working example)\n✅ Tested in production (Savannah trip research)\n✅ Published to ClawHub\n\n\n\n3.0.0 (2026-02-08): NUCLEAR OPTION - REAL AI AGENTS\n\nComplete rewrite to use sessions_spawn\nEach agent is a real spawned AI session\nNo more simulation or templates\nRequires OpenClaw environment"
      },
      {
        "title": "\"sessions_spawn not available\"",
        "body": "Cause: Not running inside OpenClaw session\nFix: Run your script inside OpenClaw"
      },
      {
        "title": "\"No module named 'tools'\"",
        "body": "Cause: Outside OpenClaw environment\nFix: The sessions tool is only available inside OpenClaw"
      },
      {
        "title": "Agents fail immediately",
        "body": "Cause: OpenClaw gateway not running\nFix: Start gateway: openclaw gateway start"
      },
      {
        "title": "This Actually Spawns Real AI Now",
        "body": "No more simulation. No more templates. When you run this inside OpenClaw:\n\nReal sessions_spawn calls happen\nReal AI sub-sessions are created\nReal reasoning occurs in each agent\nReal JSON output is generated\n\nThe agents don't just execute code — they think, create, and analyze independently using genuine AI cognition.\n\nWelcome to actual parallel AI. 🚀\n\nBuilt for OpenClaw using real sessions_spawn technology.\nPart of the OpenClaw skill ecosystem.\nHonest Edition: No simulation, just real AI."
      }
    ],
    "body": "Parallel Agents Skill - REAL AI Edition\n\n🚀 Execute tasks with ACTUAL AI-powered parallel agents using OpenClaw's sessions_spawn.\n\n⚠️ HONEST STATUS: This skill has been rewritten to use REAL AI via sessions_spawn. Previously it simulated agents with templates. Now it ACTUALLY spawns AI sub-sessions.\n\n🚨 CRITICAL USAGE NOTE\n\nThe orchestrator MUST be called from within an OpenClaw agent session, NOT as a standalone script.\n\nWhy? The tools module (which provides sessions_spawn) is only available in the agent's runtime context, not in subprocess/exec calls.\n\n✅ CORRECT: Call sessions_spawn directly from agent code (see USAGE-GUIDE.md) ❌ INCORRECT: Run orchestrator as standalone Python script via exec/subprocess\n\n📖 SEE: USAGE-GUIDE.md for tested working examples and patterns\n\n🎯 Capabilities\n\nThis skill provides 4 levels of agent automation:\n\nLevel\tFeature\tWhat It Does\n1\tTask Agents (16 types)\tSpecialized agents for content, dev, QA, docs\n2\tMeta Agents (4 types)\tAgents that create, review, refine, and orchestrate other agents\n3\tIterative Refinement\tAutomatic quality improvement loop (Creator → Reviewer → Refiner)\n4\tAgent Orchestrator\tFully autonomous workflow management - just ask and it handles everything\n\nProven Capabilities:\n\n✅ 20 concurrent agents spawned simultaneously\n✅ Smart model hierarchy - Haiku → Kimi → Opus (cost optimization)\n✅ Auto-escalation - Agents automatically use better models if needed\n✅ 100% success rate on mass creation tests with hierarchy\n✅ 3/3 agents refined to 8.5+ quality in single iteration\n✅ 4-agent hierarchy for complete autonomy\nWhat This Actually Does\n\nThis skill creates real AI sub-sessions using OpenClaw's sessions_spawn tool. Each \"agent\" is:\n\nA spawned OpenClaw session (not a subprocess)\nRunning real AI (same model as the host)\nCompletely isolated from other agents\nAble to use all the same tools as the host\n\nPrevious version: Subprocess workers with templates ❌\nCurrent version: Real spawned AI sessions ✅\n\nRequirements\nMust be run inside an OpenClaw session (for sessions_spawn access)\nOpenClaw gateway must be running\nThe sessions tool must be available in your environment\nQuick Start\n✅ Correct Usage: Direct sessions_spawn Calls\n\nFrom within an OpenClaw agent (like Scout):\n\n# Spawn multiple agents in parallel using sessions_spawn tool directly\nfrom tools import sessions_spawn\n\n# Agent 1: Research task\nresult1 = sessions_spawn(\n    task=\"Research and provide: Top 3 gay-friendly bars in Savannah. Return as JSON.\",\n    runTimeoutSeconds=90,\n    cleanup=\"delete\"\n)\n\n# Agent 2: Different research task  \nresult2 = sessions_spawn(\n    task=\"Research and provide: Best restaurants for birthday dinner. Return as JSON.\",\n    runTimeoutSeconds=90,\n    cleanup=\"delete\"\n)\n\n# Agent 3: Another parallel task\nresult3 = sessions_spawn(\n    task=\"Research and provide: Top photo spots in Savannah. Return as JSON.\",\n    runTimeoutSeconds=90,\n    cleanup=\"delete\"\n)\n\n# All 3 agents now running in parallel!\n# Check results with sessions_list() and sessions_history()\n\n❌ Incorrect Usage: Standalone Script\n# This WON'T work - tools module not available in subprocess\npython3 ~/.openclaw/skills/parallel-agents/ai_orchestrator.py\n\nBasic Usage\nfrom ai_orchestrator import RealAIParallelOrchestrator, AgentTask\n\n# Create orchestrator\norch = RealAIParallelOrchestrator(max_concurrent=5)\n\n# Define tasks\ntasks = [\n    AgentTask(\n        agent_type='content_writer_funny',\n        task_description='Write a caption about gym life',\n        input_data={'tone': 'motivational'}\n    ),\n    AgentTask(\n        agent_type='content_writer_creative',\n        task_description='Write a caption about gym life',\n        input_data={'tone': 'inspirational'}\n    ),\n]\n\n# Execute in parallel (ACTUALLY spawns AI sessions)\nresults = orch.run_parallel(tasks)\n\nHow It Works\n┌─────────────────────────────────────────────────────────┐\n│                    Main Session                         │\n│              (Your OpenClaw Instance)                   │\n│                      🧠 Host AI                         │\n└─────────────────────┬───────────────────────────────────┘\n                      │ sessions_spawn (REAL)\n                      │\n        ┌─────────────┼─────────────┬─────────────┐\n        │             │             │             │\n   ┌────▼────┐   ┌────▼────┐   ┌────▼────┐   ┌────▼────┐\n   │ Agent 1 │   │ Agent 2 │   │ Agent 3 │   │ Agent N │\n   │   📝    │   │   💻    │   │   🔍    │   │   🎨    │\n   │ REAL AI │   │ REAL AI │   │ REAL AI │   │ REAL AI │\n   │ Session │   │ Session │   │ Session │   │ Session │\n   └─────────┘   └─────────┘   └─────────┘   └─────────┘\n\nThe sessions_spawn Integration\n\nEach agent is spawned with:\n\nfrom tools import sessions_spawn\n\nresult = sessions_spawn(\n    task=agent_prompt,           # Full task description\n    agent_id=f\"agent_{type}_{id}\",  # Unique identifier\n    model=\"kimi-coding/k2p5\",     # AI model\n    runTimeoutSeconds=120,        # Max execution time\n    cleanup=\"delete\"              # Auto-cleanup\n)\n\nAvailable Agent Types\nContent Writers\nAgent Type\tPurpose\tSystem Prompt\ncontent_writer_creative\tImaginative, artistic\tRich metaphors, emotional resonance\ncontent_writer_funny\tHumorous, witty\tJokes, wordplay, relatable humor\ncontent_writer_educational\tTeaching content\tClear explanations, actionable takeaways\ncontent_writer_trendy\tViral content\tTrend-aware, culturally relevant\ncontent_writer_controversial\tDebate-sparking\tHot takes, respectful discourse\nDevelopment Agents\nAgent Type\tPurpose\tOutput\nfrontend_developer\tReact/Vue/Angular\tComponent structure, state management\nbackend_developer\tFastAPI/Flask/Django\tAPI endpoints, auth, models\ndatabase_architect\tSchema design\tTables, indexes, migrations\napi_designer\tREST/GraphQL\tOpenAPI specs, rate limits\ndevops_engineer\tCI/CD\tDocker, K8s, pipelines\nQA Agents\nAgent Type\tPurpose\tFocus\ncode_reviewer\tQuality review\tBest practices, maintainability\nsecurity_reviewer\tSecurity scan\tVulnerabilities, threats\nperformance_reviewer\tOptimization\tBottlenecks, complexity\naccessibility_reviewer\tWCAG compliance\tA11y, screen readers\ntest_engineer\tTest coverage\tUnit/integration tests\nDocumentation\nAgent Type\tPurpose\ndocumentation_writer\tREADMEs, API docs, guides\nPersonalized Agents (Jake's Suite) 🐾\n\nAgents created specifically for Jake's needs via agent_orchestrator research:\n\nAgent Type\tPurpose\tKey Features\ntravel_event_planner\tTrip content coordination\tSavannah/Atlanta/SD Pride planning, gear checklists, event schedules\ndonut_care_coordinator\tPrincess Donut management\tFeeding tracking, vet reminders, pet sitter coordination, daily updates\npup_community_engager\tPup community management\tBluesky/Twitter monitoring, DM triage, authentic pup voice engagement\nprint_project_manager\t3D printing workflow\tModel queue, filament tracking, vibecoding integration, print optimization\ntraining_assistant\tAlmac work productivity\tTraining prep, onboarding, session checklists, material templates\n\nTotal Agent Types: 25\n\n5 Content Writers\n5 Development Agents\n5 QA Agents\n1 Documentation Agent\n5 Personalized Agents 🆕\n4 Meta Agents\nMeta Agents 🔄 (Agent Creation System)\nAgent Type\tPurpose\tWhat It Does\nagent_creator\tDesigns new AI agents\tCreates complete agent definitions with prompts, schemas, examples\nagent_design_reviewer\tValidates agent designs\tReviews quality, completeness, production readiness (scores 0-10)\nagent_refiner\tImproves agent designs\tApplies fixes based on review feedback to reach target scores\nagent_orchestrator\tMaster coordinator\tPlans workflows, spawns agents, coordinates execution, compiles results\n\nThe 4-Agent Hierarchy:\n\nLevel 4: USER\n    ↓ asks\nLevel 3: AGENT_ORCHESTRATOR\n    ↓ plans, spawns, coordinates\nLevel 2: Meta Agents (creator, reviewer, refiner)\n    ↓ designs, reviews, refines\nLevel 1: Task Agents (content writers, developers, QA)\n    ↓ does work\nLevel 0: Actual Tasks\n\n\nTotal Agent Types: 20\n\n5 Content Writers\n5 Development Agents\n5 QA Agents\n1 Documentation Agent\n4 Meta Agents 🆕\n\nWorkflow 1: Simple Creation (2 agents)\n\nfrom ai_orchestrator import (\n    RealAIParallelOrchestrator,\n    create_meta_agent_workflow\n)\n\norch = RealAIParallelOrchestrator()\n\n# Define agents to create\nnew_agents = [\n    {'name': 'crypto_analyst', 'purpose': 'Analyze crypto trends'},\n    {'name': 'content_strategist', 'purpose': 'Plan content calendars'}\n]\n\n# Creates: 2 creators + 2 reviewers (4 tasks)\ntasks = create_meta_agent_workflow(new_agents)\nresults = orch.run_parallel(tasks)\n\n\nWorkflow 2: Iterative Refinement (3-agent loop)\n\n# The full 3-agent refinement workflow:\n# Creator → Reviewer (scores) → Refiner (fixes) → Reviewer (verifies)\n# Repeats until score >= 8.5\n\nagents_to_refine = [\n    {'name': 'my_agent', 'current_score': 7.4, 'target': 8.5}\n]\n\n# This runs the full loop automatically\nresults = orch.run_iterative_refinement(agents_to_refine)\n# Result: 7.4 → 8.5+ ✅\n\n\nWorkflow 3: Orchestrated Mass Creation (autonomous)\n\n# Spawn the orchestrator to handle everything:\n# - Plans workflow\n# - Spawns all agents\n# - Coordinates execution\n# - Handles refinements\n# - Compiles final report\n\nresult = sessions_spawn(\n    task=\"Create 5 new agents and ensure all score 8.5+\",\n    agent_type='agent_orchestrator',\n    timeout=600\n)\n\n# The orchestrator does everything autonomously!\n\n\nThis enables agent bootstrapping - the system creates and improves itself!\n\nData Structures\nAgentTask\n@dataclass\nclass AgentTask:\n    agent_type: str           # Type from registry (required)\n    task_description: str     # What to do (required)\n    input_data: Dict          # Input parameters (optional)\n    task_id: str             # Unique ID (auto-generated)\n    timeout_seconds: int     # Max time (default: 120)\n    output_format: str       # json|markdown|code|text\n\nAgentResult\n@dataclass\nclass AgentResult:\n    task_id: str             # Matches AgentTask\n    agent_type: str          # Agent that produced this\n    status: str              # pending|running|completed|failed\n    output: Any              # Generated content (agent-dependent format)\n    execution_time: float    # Time taken\n    error: str              # Error message if failed\n    session_key: str        # Spawned session identifier\n\nExamples\nExample 1: Generate Multiple Content Styles\nfrom ai_orchestrator import RealAIParallelOrchestrator, create_content_team\n\norch = RealAIParallelOrchestrator(max_concurrent=5)\ntasks = create_content_team(\"Monday motivation\", platform=\"bluesky\")\n\n# This spawns 5 REAL AI agents\nresults = orch.run_parallel(tasks)\n\nprint(\"Agents spawned! Each is generating content...\")\nprint(\"Check sessions_list() to see running agents\")\n\nExample 2: Full-Stack Development Team\nfrom ai_orchestrator import RealAIParallelOrchestrator, create_dev_team\n\norch = RealAIParallelOrchestrator(max_concurrent=5)\ntasks = create_dev_team(\"TaskManager\", ['auth', 'tasks', 'teams'])\n\n# Spawns 5 dev agents in parallel\nresults = orch.run_parallel(tasks)\n\n# Each agent designs their layer independently\n# - Frontend agent designs React components\n# - Backend agent designs FastAPI routes\n# - Database agent designs schema\n# - etc.\n\nExample 3: Code Review Team\nfrom ai_orchestrator import RealAIParallelOrchestrator, create_review_team\n\ncode = open('app.py').read()\n\norch = RealAIParallelOrchestrator(max_concurrent=5)\ntasks = create_review_team(code)\n\n# Spawns 5 reviewers simultaneously\nresults = orch.run_parallel(tasks)\n\n# Each reviews from different angle:\n# - Code quality\n# - Security\n# - Performance\n# - Accessibility\n# - Test coverage\n\nExample 4: Meta-Agent System (Agents Creating Agents) 🔄\nfrom ai_orchestrator import (\n    RealAIParallelOrchestrator,\n    create_meta_agent_workflow\n)\n\norch = RealAIParallelOrchestrator(max_concurrent=6)\n\n# Define new agents to create\nnew_agents = [\n    {\n        'name': 'social_media_analyst',\n        'purpose': 'Analyze social media performance',\n        'domain': 'social media analytics',\n        'capabilities': ['engagement analysis', 'trend identification']\n    },\n    {\n        'name': 'bug_hunter',\n        'purpose': 'Find bugs in code',\n        'domain': 'software QA',\n        'capabilities': ['static analysis', 'edge case detection']\n    },\n    {\n        'name': 'api_documenter',\n        'purpose': 'Generate API docs',\n        'domain': 'technical writing',\n        'capabilities': ['endpoint extraction', 'example generation']\n    }\n]\n\n# Creates 6 tasks: 3 creators + 3 reviewers\ntasks = create_meta_agent_workflow(new_agents)\nresults = orch.run_parallel(tasks)\n\n# Result: 3 complete agent definitions + 3 quality reviews\n# All created entirely by AI in parallel!\n\n\nThis is agent bootstrapping - the system creates itself!\n\nExample 5: Mass Agent Creation (10+ Agents at Once) 🔥\n\nProven Capability: The system has been tested with 20 concurrent agents (10 creators + 10 reviewers) all spawned simultaneously.\n\nfrom ai_orchestrator import RealAIParallelOrchestrator, AgentTask\n\norch = RealAIParallelOrchestrator(max_concurrent=10)\n\n# Define 10 new agents to create\nnew_agents = [\n    {'name': 'engagement_optimizer', 'purpose': 'Analyze social media posts', \n     'domain': 'social media', 'capabilities': ['analytics', 'optimization']},\n    {'name': 'workout_designer', 'purpose': 'Create gym/home workouts',\n     'domain': 'fitness', 'capabilities': ['program design', 'adaptation']},\n    {'name': 'email_drafter', 'purpose': 'Write professional/personal emails',\n     'domain': 'communication', 'capabilities': ['tone adaptation', 'drafting']},\n    # ... more agents\n]\n\n# Create all 10 agents + 10 reviewers = 20 parallel agents!\nall_tasks = []\nfor agent in new_agents:\n    # Add creator\n    all_tasks.append(AgentTask(\n        agent_type='agent_creator',\n        task_description=f\"Design agent: {agent['name']}\",\n        input_data=agent,\n        timeout_seconds=180\n    ))\n    # Add reviewer\n    all_tasks.append(AgentTask(\n        agent_type='agent_design_reviewer',\n        task_description=f\"Review {agent['name']}\",\n        input_data={'agent_name': agent['name']},\n        timeout_seconds=120\n    ))\n\n# SPAWN 20 AGENTS SIMULTANEOUSLY\nresults = orch.run_parallel(all_tasks)\n\n\nReal-World Results (2026-02-08 Test):\n\n✅ 10 Agent Creators spawned successfully\n✅ 10 Design Reviewers spawned successfully\n✅ All 20 completed without errors\n✅ Average quality score: 8.1/10\n✅ Production-ready agent definitions created\n\nPractical Limit: ~20-50 concurrent agents (depends on system resources)\n\nSee: examples/mass_agent_creation.py for full implementation.\n\nCollecting Results\n\nAgents return their output in their session transcript. To collect:\n\n# After spawning, poll for results\nfrom tools import sessions_list, sessions_history\n\n# Check which agents have completed\nsessions = sessions_list(agent_id_pattern=\"agent_*\")\n\nfor session in sessions:\n    if session['status'] == 'completed':\n        history = sessions_history(session['sessionKey'])\n        # Parse JSON from final assistant message\n        output = json.loads(history[-1]['content'])\n\n\nNote: Full result collection is implemented in the orchestrator. Results are available via results attribute after spawning.\n\nArchitecture Notes\nWhy sessions_spawn?\n\nPrevious implementations tried:\n\nThreading - Limited by Python GIL, not truly parallel\nMultiprocessing - macOS spawn issues, complex IPC\nSubprocess workers - Templates, not real AI\n\nsessions_spawn is the solution:\n\nTrue isolation (separate sessions)\nFull AI capabilities (same model)\nBuilt into OpenClaw\nAutomatic cleanup\nLimitations\nOpenClaw dependency - Must run inside OpenClaw session\nResult collection - Requires polling sessions_list\nCost - Each spawn = separate API call (but same model/credentials)\nTimeout - Agents limited to 120 seconds by default\nFile Structure\n~/.openclaw/skills/parallel-agents/\n├── README.md                          # Quick start guide\n├── SKILL.md                           # Complete documentation\n├── USAGE-GUIDE.md                     # Practical examples and patterns\n├── ai_orchestrator.py                 # Core orchestrator code\n├── helpers.py                         # Auto-retry helper functions\n└── examples/                          # Working examples\n    ├── README.md                      # Examples documentation\n    └── simple_parallel_research.py    # Simple example\n\nVersion History\n\n3.2.0 (2026-02-08): SMART MODEL HIERARCHY\n\n✅ Added intelligent model escalation (Haiku → Kimi → Opus)\n✅ Cost optimization: Try cheapest model first, escalate if needed\n✅ Updated helpers.py with spawn_with_model_hierarchy()\n✅ Auto-escalation in spawn_with_retry() and spawn_parallel_with_retry()\n✅ Comprehensive docs on model selection and cost savings\n✅ Tested: Haiku completes simple tasks successfully\n\n3.1.0 (2026-02-08): PRODUCTION READY\n\n✅ Added auto-retry helpers (spawn_with_retry, spawn_parallel_with_retry)\n✅ Cleaned up development artifacts (removed 18 outdated files)\n✅ Added comprehensive documentation (README, USAGE-GUIDE)\n✅ Simplified examples (one clear working example)\n✅ Tested in production (Savannah trip research)\n✅ Published to ClawHub\n\n3.0.0 (2026-02-08): NUCLEAR OPTION - REAL AI AGENTS\n\nComplete rewrite to use sessions_spawn\nEach agent is a real spawned AI session\nNo more simulation or templates\nRequires OpenClaw environment\nTroubleshooting\n\"sessions_spawn not available\"\n\nCause: Not running inside OpenClaw session\nFix: Run your script inside OpenClaw\n\n\"No module named 'tools'\"\n\nCause: Outside OpenClaw environment\nFix: The sessions tool is only available inside OpenClaw\n\nAgents fail immediately\n\nCause: OpenClaw gateway not running\nFix: Start gateway: openclaw gateway start\n\nThis Actually Spawns Real AI Now\n\nNo more simulation. No more templates. When you run this inside OpenClaw:\n\nReal sessions_spawn calls happen\nReal AI sub-sessions are created\nReal reasoning occurs in each agent\nReal JSON output is generated\n\nThe agents don't just execute code — they think, create, and analyze independently using genuine AI cognition.\n\nWelcome to actual parallel AI. 🚀\n\nBuilt for OpenClaw using real sessions_spawn technology. Part of the OpenClaw skill ecosystem. Honest Edition: No simulation, just real AI."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/jdalbright/parallel-agents",
    "publisherUrl": "https://clawhub.ai/jdalbright/parallel-agents",
    "owner": "jdalbright",
    "version": "3.2.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/parallel-agents",
    "downloadUrl": "https://openagent3.xyz/downloads/parallel-agents",
    "agentUrl": "https://openagent3.xyz/skills/parallel-agents/agent",
    "manifestUrl": "https://openagent3.xyz/skills/parallel-agents/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/parallel-agents/agent.md"
  }
}