Agent Orchestrator

# Agent Orchestrator

通过将复杂任务分解为子任务、生成自治子代理并整合其工作来编排任务。

## Core Workflow

### Phase 1: Task Decomposition

分析宏观任务并将其拆分为独立的、可并行的子任务：

``` 1. Identify the end goal and success criteria 2. List all major components/deliverables required 3. Determine dependencies between components 4. Group independent work into parallel subtasks 5. Create a dependency graph for sequential work ```

**Decomposition Principles:** - Each subtask should be completable in isolation - Minimize inter-agent dependencies - Prefer broader, autonomous tasks over narrow, interdependent ones - Include clear success criteria for each subtask

### Phase 2: Agent Generation

为每个子任务创建一个子代理工作区：

```bash python3 scripts/create_agent.py <agent-name> --workspace <path> ```

这会创建： ``` <workspace>/<agent-name>/ ├── SKILL.md # Generated skill file for the agent ├── inbox/ # Receives input files and instructions ├── outbox/ # Delivers completed work ├── workspace/ # Agent's working area └── status.json # Agent state tracking ```

**Generate SKILL.md dynamically**，其中包含： - Agent's specific role and objective - Tools and capabilities needed - Input/output specifications - Success criteria - Communication protocol

参见 [references/sub-agent-templates.md](references/sub-agent-templates.md) 获取预构建模板。

### Phase 3: Agent Dispatch

通过以下方式初始化每个代理：

1. Writing task instructions to `inbox/instructions.md` 2. Copying required input files to `inbox/` 3. Setting `status.json` to `{"state": "pending", "started": null}` 4. Spawning the agent using the Task tool:

```python # Spawn agent with its generated skill Task( description=f"{agent_name}: {brief_description}", prompt=f""" Read the skill at {agent_path}/SKILL.md and follow its instructions. Your workspace is {agent_path}/workspace/ Read your task from {agent_path}/inbox/instructions.md Write all outputs to {agent_path}/outbox/ Update {agent_path}/status.json when complete. """, subagent_type="general-purpose" ) ```

### Phase 4: Monitoring (Checkpoint-based)

对于完全自治的代理，只需极少的监控：

```python # Check agent completion def check_agent_status(agent_path): status = read_json(f"{agent_path}/status.json") return status.get("state") == "completed" ```

定期检查每个代理的 `status.json`。代理在完成时会更新此文件。

### Phase 5: Consolidation

所有代理完成后：

1. **Collect outputs** from each agent's `outbox/` 2. **Validate deliverables** against success criteria 3. **Merge/integrate** outputs as needed 4. **Resolve conflicts** if multiple agents touched shared concerns 5. **Generate summary** of all work completed

```python # Consolidation pattern for agent in agents: outputs = glob(f"{agent.path}/outbox/*") validate_outputs(outputs, agent.success_criteria) consolidated_results.extend(outputs) ```

### Phase 6: Dissolution & Summary

整合后：

1. **Archive agent workspaces** (optional) 2. **Clean up temporary files** 3. **Generate final summary**: - What was accomplished per agent - Any issues encountered - Final deliverables location - Time/resource metrics

```python python3 scripts/dissolve_agents.py --workspace <path> --archive ```

## File-Based Communication Protocol

参见 [references/communication-protocol.md](references/communication-protocol.md) 获取详细规范。

**Quick Reference:** - `inbox/` - Read-only for agent, written by orchestrator - `outbox/` - Write-only for agent, read by orchestrator - `status.json` - Agent updates state: `pending` → `running` → `completed` | `failed`

## Example: Research Report Task

``` Macro Task: "Create a comprehensive market analysis report"

Decomposition: ├── Agent: data-collector │ └── Gather market data, competitor info, trends ├── Agent: analyst │ └── Analyze collected data, identify patterns ├── Agent: writer │ └── Draft report sections from analysis └── Agent: reviewer └── Review, edit, and finalize report

Dependency: data-collector → analyst → writer → reviewer ```

## Sub-Agent Templates

[references/sub-agent-templates.md](references/sub-agent-templates.md) 中针对常见代理类型的预构建模板：

- **Research Agent** - Web search, data gathering - **Code Agent** - Implementation, testing - **Analysis Agent** - Data processing, pattern finding - **Writer Agent** - Content creation, documentation - **Review Agent** - Quality assurance, editing - **Integration Agent** - Merging outputs, conflict resolution

## Best Practices

1. **Start small** - Begin with 2-3 agents, scale as patterns emerge 2. **Clear boundaries** - Each agent owns specific deliverables 3. **Explicit handoffs** - Use structured files for agent communication 4. **Fail gracefully** - Agents report failures; orchestrator handles recovery 5. **Log everything** - Status files track progress for debugging