Agency Agents Router -- Route and orchestrate specialized agents#

Repo： Staok/agency-agents-router-skill.

Overview#

If openclaw.json has multiple agents configured under agents.list, this skill discovers them and orchestrates appropriate agents for any given task.

In a default OpenClaw setup, only the main agent's prompt is active. Other configured agents are invisible. Agent Router solves this by injecting agent awareness and orchestration logic into the main agent's prompt.

Prerequisites#

This skill is the router — the agent definitions must be installed separately. Without them, agents.json will be empty and no orchestration can happen.

User (manual): Install agency-agents-zh agents, then restart gateway:

bash

git clone https://github.com/jnMetaCode/agency-agents-zh.git
cd agency-agents-zh
./scripts/convert.sh --tool openclaw
./scripts/install.sh --tool openclaw

# Restart OpenClaw gateway
openclaw gateway restart

Agent (auto): After user confirms installation, the agent runs:

bash

cd ~/.openclaw/workspace/skills/agency-agents-router
python3 scripts/rebuild_index.py --clone

Then verifies agents appear in ~/.openclaw/openclaw.json under agents.list.

If agents.json is missing or empty, the agent MUST first check whether agency-agents-zh is installed. If not, instruct the user with the manual steps above. Do NOT attempt to orchestrate without agents.

How It Works#

The main agent, equipped with this skill, becomes an orchestrator:

1. Receive a task description
2. Classify the task intent using the Task Archetypes table — this determines the agent selection strategy
3. Detect ambiguity: if the task crosses archetype boundaries, ask ONE clarifying question (audience, genre, format, depth) then proceed
4. Pre-research: for factual or time-sensitive tasks, the orchestrator should do live web searches first to ground agents in current reality, not stale training data
5. Look up agents.json to find matching agents based on the clarified intent
6. Design an execution plan: which agents to run, in what order, with what dependencies
7. Execute via sessions_spawn(agentId=xxx, mode="run"); domain-expert agents should be prompted to use web_search / web_fetch for factual grounding
8. Aggregate results and present to the user

Research Protocol: Prefer Live Web Data#

For factual, time-sensitive, or comparative tasks, agents should rely on live web data rather than training data alone.

When to search the web#

ScenarioWho searchesFactual claims, current data, time-sensitive topicsOrchestrator (pre-research) + domain agentsComparison / ranking / landscape surveysOrchestrator (pre-research) + domain agentsResearch & Analysis or Content Creation archetypesDomain agentsTechnical Writing with version-specific detailsDomain agents

Pre-research (orchestrator)#

Before dispatching agents for factual tasks: 2-3 web_search queries → web_fetch 2-3 key sources → include findings in sub-agent prompts.

Sub-agent prompt boilerplate#

text

Prefer web_search/web_fetch for latest information over training data.
Cite URLs and dates for factual claims.
Mark unverifiable items as "[待确认]".

CRITICAL: Classify BEFORE selecting agents#

Do NOT jump from "receive task" directly to "look up agents". Without first classifying the task archetype, the same keyword ("write an analysis article") will be interpreted inconsistently — sometimes as research, sometimes as content creation. Step 2 (classification) is mandatory. Step 3 (ambiguity check) is mandatory when keywords span archetypes.

Task Archetypes#

Every task MUST be classified into one of these archetypes BEFORE agent selection. The archetype determines the primary agent role and whether domain-expert agents play lead or supporting roles.

ArchetypeTypical KeywordsAgent Selection StrategyExampleContent Creationwrite article, blog post, essay, deep-dive, long-form, copywriting, storytellingLead: narrative/creative agents. Supporting: domain experts for fact-checking."Write a deep-dive article about AI Agent trends"Research & Analysisanalyze, research, investigate, evaluate, feasibility, industry report, market studyLead: research + domain experts. Multi-perspective parallel."Analyze the feasibility of an AI note-taking app"Technical Writingtechnical docs, README, API docs, design docs, specLead: technical writer. Supporting: relevant engineering roles."Write API documentation for this service"Engineeringreview code, fix bug, refactor, optimize, implement featureLead: language/framework-specific engineer. Supporting: security, testing."Review this PR for security and performance"Product Designdesign, UI, UX, prototype, product spec, wireframeLead: product manager or designer. Supporting: UX researcher."Design a SaaS pricing page"Business Strategybusiness plan, pricing, go-to-market, funding, monetizationLead: product manager or strategist. Supporting: finance, marketing."Plan a go-to-market strategy for a B2B SaaS"Code Generationwrite code, build, implement, scaffold, create appLead: language/framework-specific engineer (single agent typically)."Build a REST API with FastAPI"Multi-Perspective Auditreview holistically, due diligence, full assessmentLead: domain-general coordinator. Parallel specialists."Full technical due diligence on this startup"

Decision Heuristic#

When the task says "write an article about X analysis", ask yourself:

• Is the primary goal to inform and engage a broad audience? → Content Creation (narrative agents lead, domain experts support)
• Is the primary goal to produce a structured, evidence-heavy report for decision-makers? → Research & Analysis (domain experts lead)
• Is the audience implied by the user's profile? If the user is a content creator → Content Creation. If the user is an engineer → Research & Analysis. But still confirm if ambiguous.

Ambiguity Detection & Clarification Protocol#

Trigger Keywords#

These keywords frequently span multiple archetypes. When detected, the orchestrator MUST ask for clarification before selecting agents:

Ambiguous KeywordPossible ArchetypesWhat to Clarify"analysis article" / "deep analysis article"Content Creation OR Research & AnalysisTarget audience? Publishing channel?"design" / "design a solution"Product Design OR Engineering OR Business StrategyWhat kind of design?"evaluate" / "assess"Research & Analysis OR EngineeringFrom which perspective?"plan" / "proposal"Business Strategy OR Product Design OR EngineeringPlan for what?"build" / "create"Code Generation OR Product Design OR Content CreationBuild what exactly?

Clarification Protocol#

When ambiguity is detected:

1. Identify the ambiguous dimension(s): audience? genre? format? depth? technical level?
2. Ask that resolves all ambiguity at once — do not ask multiple rounds
3. Frame the question to reveal the archetype: "Is this for a general-audience publication (Content Creation) or a technical decision-making report (Research)?"
4. If the user's profile strongly suggests one archetype, still confirm if ambiguity crosses the Content/Research boundary

Bad (multiple rounds):

"Who is the audience?" → wait → "What format?" → wait → "How technical?"

Good (single round):

"Target audience and channel for this article? e.g., general readers on Zhihu/WeChat (Content Creation route), or technical decision-makers as an internal report (Research route)?"

Orchestration Patterns#

Pattern 1: Single Agent#

A task clearly falls under one agent's expertise. Spawn directly.

text

User: "Review this C++ code for bugs"
  Archetype: Engineering
  -> engineering-code-reviewer

Pattern 2: Parallel (Independent Agents)#

Spawn multiple agents simultaneously for independent subtasks.

text

User: "Review this PR"
  -> engineering-code-reviewer (code quality)
  -> engineering-security-engineer (security audit)
  -> testing-performance-benchmarker (performance check)
  All three run in parallel, results merged at the end.

Pattern 3: Sequential / Pipeline#

Agent B depends on Agent A's output. Spawn A first, feed result into B.

text

User: "Design and document this API"
  -> engineering-software-architect (design the API)
  -> engineering-technical-writer (document the design)

Pattern 4: DAG (Directed Acyclic Graph)#

Complex workflows with parallel branches and merge points.

text

User: "Technical design review for a new feature"
  -> engineering-software-architect (system design)
     +-> engineering-security-engineer (security review)  --+
     +-> engineering-backend-architect (backend review)  ----+-> product-manager (summary)
     +-> engineering-database-optimizer (schema review)  ----+

Pattern 5: Multi-Perspective Analysis (Research)#

Multiple disciplinary perspectives for evidence-heavy analysis. Domain experts should web-search for current data.

text

User: "Is an AI-powered note-taking app viable?"
  Pre-research: orchestrator web-searches market landscape
  -> product-trend-researcher (market analysis)
  -> engineering-software-architect (technical feasibility)
  -> finance-financial-forecaster (cost/revenue modeling)
  -> marketing-seo-specialist (go-to-market analysis)

Pattern 6: Content Creation#

Narrative design + audience psychology + platform-aware execution. Domain experts play supporting roles (fact-checking, background research), NOT lead roles.

text

User: "Write a deep-dive article about AI Agent trends"
  Pre-research: orchestrator web-searches current landscape
  -> domain expert (background research — web-search for latest)
  -> academic-narratologist (story arc, hooks, rhythm)
  -> academic-psychologist (reader psychology, engagement)
  -> marketing-content-creator (platform voice, shareability)

  Workflow: orchestrator pre-research → domain expert FIRST (live web search) →
            creative agents in PARALLEL → synthesizer produces final draft.

Key distinction from Pattern 5 (Research):

DimensionPattern 5 (Research)Pattern 6 (Content Creation)Primary goalEvidence, accuracy, completenessEngagement, readability, impactDomain expertsLead roleSupporting role (fact-check only)Output formatStructured report with sectionsNarrative with hooks, flow, voiceSuccess metricDecision-makers can act on itReaders finish it and share it

Agent Index#

The lookup table in agents.json maps every configured agent to:

FieldDescriptionagentIdAgent ID in openclaw.json — used with sessions_spawnname_zhChinese name (from agency-agents-zh README)descriptionDetailed capability summary extracted from agent .md frontmatterexpertiseKey skills (from README table)scenarioUse case (from README table)sectionDepartment grouping

Data sources: agency-agents-zh (194 agents) + agency-agents upstream (21 agents).

Usage Commands#

CommandDescription/agentsList all agents grouped by department/agents <dept>Filter by department/agent search <keyword>Search agents by keyword/agent <id> <task>Explicitly invoke one specific agent

For most tasks, no command is needed. Describe the task naturally and the main agent will determine the orchestration plan.

sessions_spawn Usage#

json

sessions_spawn(agentId="<agentId>", task="<task description>", mode="run")

• Sub-agents execute in their own workspace
• Results return to the main session automatically
• Multiple spawn calls without inter-dependencies can be invoked in parallel (single turn)
• Dependent calls: spawn, wait for result, then spawn the next

Maintenance#

bash

# Rebuild with local agency-agents-zh repo:
python3 scripts/rebuild_index.py --repo /path/to/agency-agents-zh

# Auto-clone and rebuild from scratch:
python3 scripts/rebuild_index.py --clone --fetch

Credits#

• Agent descriptions from agency-agents-zh (194 agents)
• Additional descriptions from agency-agents upstream (21 agents)
• Orchestration patterns inspired by Agency Orchestrator