Agent Orchestrator

Agent Orchestrator

Orchestrate complex tasks by decomposing them into subtasks, spawning autonomous sub-agents, and consolidating their work.

Core Workflow

Phase 1: Task Decomposition

Analyze the macro task and break it into independent, parallelizable subtasks:

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

For each subtask, create a sub-agent workspace:

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

This creates:

<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 with:

• Agent's specific role and objective
• Tools and capabilities needed
• Input/output specifications
• Success criteria
• Communication protocol

See references/sub-agent-templates.md for pre-built templates.

Phase 3: Agent Dispatch

Initialize each agent by:

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:

# 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)

For fully autonomous agents, minimal monitoring is needed:

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

Periodically check status.json for each agent. Agents update this file upon completion.

Phase 5: Consolidation

Once all agents complete:

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

# 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

After consolidation:

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

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

File-Based Communication Protocol

See references/communication-protocol.md for detailed specs.

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

Pre-built templates for common agent types in 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

File-Based Communication Protocol

Specification for how orchestrator and sub-agents communicate via files.

Directory Structure

Each agent has a standardized workspace:

agent-workspace/
├── SKILL.md           # Agent's skill definition (read-only for agent)
├── inbox/             # Input from orchestrator → agent
│   ├── instructions.md    # Task description and requirements
│   └── [input files]      # Any files needed for the task
├── outbox/            # Output from agent → orchestrator
│   └── [deliverables]     # Task outputs
├── workspace/         # Agent's private working area
│   └── [temp files]       # Intermediate work products
└── status.json        # Agent state tracking

Status File Specification

status.json tracks agent lifecycle:

{
  "state": "pending|running|completed|failed",
  "started": "2024-01-15T10:30:00Z",
  "completed": "2024-01-15T11:45:00Z",
  "error": null,
  "progress": {
    "current_step": "analyzing_data",
    "steps_completed": 3,
    "total_steps": 5
  },
  "metrics": {
    "files_processed": 12,
    "outputs_generated": 4
  }
}

State Transitions

pending → running → completed
                 ↘ failed

State Definitions:

• pending: Agent created but not yet started
• running: Agent actively working on task
• completed: Agent finished successfully
• failed: Agent encountered unrecoverable error

Update Protocol

1. Orchestrator sets initial state to pending 2. Agent updates to running when starting work 3. Agent updates to completed or failed when done 4. Orchestrator reads to determine next action

Inbox Protocol

instructions.md Format

# Task: {TASK_NAME}

## Objective
{Clear statement of what needs to be accomplished}

## Context
{Background information relevant to the task}

## Inputs Provided
- `input_file_1.txt` - Description of what this contains
- `data/` - Directory containing...

## Requirements
1. {Specific requirement 1}
2. {Specific requirement 2}

## Success Criteria
- [ ] {Measurable outcome 1}
- [ ] {Measurable outcome 2}

## Constraints
- {Time/resource constraints}
- {Quality standards}

## Output Expectations
- Place main deliverable in `outbox/{filename}`
- Include summary in `outbox/summary.md`

File Transfer Rules

• Orchestrator copies all needed files to inbox/
• Agent treats inbox/ as read-only
• Original files remain with orchestrator
• Large files: use references/paths instead of copies

Outbox Protocol

Required Outputs

Every agent must produce at minimum: 1. Primary deliverable(s) - The actual work product 2. summary.md - Brief summary of what was done

Optional Outputs

• changelog.md - Detailed log of actions taken
• issues.md - Problems encountered and how resolved
• metadata.json - Structured data about outputs

Output Naming Convention

outbox/
├── {primary_deliverable}.{ext}
├── summary.md
├── data/           # If multiple data outputs
│   ├── file1.csv
│   └── file2.json
└── metadata.json

Workspace Protocol

The workspace/ directory is the agent's private area:

• Agent can create any files needed for processing
• Orchestrator ignores this directory during collection
• Cleanup optional - agents may leave or clean workspace
• Useful for intermediate results, caches, temp files

Error Handling

Failure Protocol

When an agent fails:

1. Update status.json:

{
  "state": "failed",
  "error": {
    "type": "ValidationError",
    "message": "Input file format invalid",
    "details": "Expected CSV, got JSON",
    "recoverable": true
  }
}

2. Write outbox/error_report.md:

# Error Report

## Error Type
ValidationError

## Description
Input file format was invalid. Expected CSV format but received JSON.

## Attempted Recovery
Tried to convert JSON to CSV but data structure incompatible.

## Suggested Resolution
Provide input as CSV with columns: id, name, value

## Partial Work
Any completed work before failure is in outbox/partial/

Recovery Options

Orchestrator can: 1. Retry - Re-run with same inputs 2. Fix and retry - Correct inputs and re-run 3. Skip - Mark as failed, continue with other agents 4. Escalate - Request human intervention

Dependency Handling

When agents depend on each other's outputs:

Manifest File

Orchestrator creates inbox/dependencies.json:

{
  "depends_on": [
    {
      "agent": "data-collector",
      "outputs": ["outbox/data.json", "outbox/sources.md"],
      "copy_to": "inbox/source_data/"
    }
  ],
  "wait_for": ["data-collector", "schema-validator"]
}

Sequential Execution

# Orchestrator pattern for dependencies
def execute_with_dependencies(agent, dependencies):
    # Wait for all dependencies
    for dep in dependencies:
        while not is_completed(dep):
            wait()

    # Copy dependency outputs to agent inbox
    for dep in dependencies:
        copy_outputs(dep.outbox, agent.inbox)

    # Start agent
    spawn_agent(agent)

Parallel Execution

Independent agents can run simultaneously:

# Spawn all independent agents at once
parallel_agents = identify_independent_agents(task_graph)
for agent in parallel_agents:
    spawn_agent(agent)  # Non-blocking

# Wait for all to complete
while not all_completed(parallel_agents):
    check_status_periodically()

Message Passing Pattern

For complex inter-agent communication:

Shared Message Queue (Optional)

orchestrator-workspace/
└── messages/
    ├── {agent-a}_to_{agent-b}_001.json
    └── {agent-b}_to_{agent-a}_002.json

Message format:

{
  "from": "agent-a",
  "to": "agent-b",
  "timestamp": "2024-01-15T10:30:00Z",
  "type": "data_ready|question|answer|update",
  "content": { ... }
}

Note: For fully autonomous agents, prefer one-directional communication via inbox/outbox over message passing.

Sub-Agent Templates

Pre-built SKILL.md templates for common agent types. Copy and customize as needed.

Table of Contents

1. Research Agent 2. Code Agent 3. Analysis Agent 4. Writer Agent 5. Review Agent 6. Integration Agent

---

Research Agent

Specializes in gathering information from web searches, documents, and data sources.

---
name: research-agent-{task_id}
description: |
  Autonomous research agent for gathering and organizing information.
  Reads task from inbox/instructions.md, outputs findings to outbox/.
---

# Research Agent

## Objective
{INSERT_OBJECTIVE}

## Tools Available
- WebSearch: Search the web for information
- WebFetch: Retrieve specific web pages
- Read: Read local files for context

## Workflow

1. Read `inbox/instructions.md` for research requirements
2. Update `status.json` to `{"state": "running"}`
3. Execute research:
   - Identify key search queries
   - Gather information from multiple sources
   - Cross-reference and validate findings
   - Organize by relevance
4. Write outputs:
   - `outbox/findings.md` - Main research findings
   - `outbox/sources.md` - List of all sources with citations
   - `outbox/summary.md` - Executive summary (max 500 words)
5. Update `status.json` to `{"state": "completed"}`

## Success Criteria
- All required topics covered
- Sources properly cited
- Findings organized and actionable

## Communication Protocol
- Read from: `inbox/`
- Write to: `outbox/`
- Status: `status.json`

---

Code Agent

Specializes in writing, testing, and refactoring code.

---
name: code-agent-{task_id}
description: |
  Autonomous coding agent for implementation tasks.
  Reads specifications from inbox/, delivers code to outbox/.
---

# Code Agent

## Objective
{INSERT_OBJECTIVE}

## Tools Available
- Read/Write/Edit: File operations
- Bash: Execute commands, run tests
- Glob/Grep: Search codebase

## Workflow

1. Read `inbox/instructions.md` for implementation requirements
2. Read `inbox/context/` for existing code context (if provided)
3. Update `status.json` to `{"state": "running"}`
4. Execute implementation:
   - Analyze requirements
   - Review existing patterns in codebase
   - Write implementation
   - Write tests
   - Run tests and fix issues
5. Write outputs:
   - `outbox/code/` - Implementation files
   - `outbox/tests/` - Test files
   - `outbox/changelog.md` - What was changed/created
6. Update `status.json` to `{"state": "completed"}`

## Success Criteria
- All tests passing
- Code follows existing patterns
- No linting errors
- Clear documentation/comments

## Communication Protocol
- Read from: `inbox/`
- Write to: `outbox/`
- Status: `status.json`

---

Analysis Agent

Specializes in data analysis, pattern recognition, and insights generation.

---
name: analysis-agent-{task_id}
description: |
  Autonomous analysis agent for processing data and generating insights.
  Reads data from inbox/, outputs analysis to outbox/.
---

# Analysis Agent

## Objective
{INSERT_OBJECTIVE}

## Tools Available
- Read: Read data files
- Bash: Run Python/analysis scripts
- Write: Output results

## Workflow

1. Read `inbox/instructions.md` for analysis requirements
2. Read `inbox/data/` for input data files
3. Update `status.json` to `{"state": "running"}`
4. Execute analysis:
   - Load and validate data
   - Apply analysis techniques
   - Identify patterns and anomalies
   - Generate visualizations if needed
   - Draw conclusions
5. Write outputs:
   - `outbox/analysis.md` - Detailed analysis
   - `outbox/insights.md` - Key insights and recommendations
   - `outbox/data/` - Processed data files
   - `outbox/charts/` - Visualizations (if any)
6. Update `status.json` to `{"state": "completed"}`

## Success Criteria
- All data processed accurately
- Insights are actionable
- Conclusions supported by evidence
- Methodology documented

## Communication Protocol
- Read from: `inbox/`
- Write to: `outbox/`
- Status: `status.json`

---

Writer Agent

Specializes in content creation, documentation, and communication.

---
name: writer-agent-{task_id}
description: |
  Autonomous writing agent for creating documents and content.
  Reads briefs from inbox/, delivers content to outbox/.
---

# Writer Agent

## Objective
{INSERT_OBJECTIVE}

## Tools Available
- Read: Read input materials
- Write: Create content files
- Skills: docx, pdf, pptx (as needed)

## Workflow

1. Read `inbox/instructions.md` for writing requirements
2. Read `inbox/source_material/` for reference content
3. Update `status.json` to `{"state": "running"}`
4. Execute writing:
   - Understand audience and purpose
   - Create outline
   - Draft content
   - Self-review and polish
   - Format appropriately
5. Write outputs:
   - `outbox/draft.{format}` - Main content deliverable
   - `outbox/outline.md` - Structure used
   - `outbox/notes.md` - Any considerations for reviewer
6. Update `status.json` to `{"state": "completed"}`

## Success Criteria
- Matches specified tone and style
- Appropriate length
- Clear and well-organized
- Grammar and spelling correct

## Communication Protocol
- Read from: `inbox/`
- Write to: `outbox/`
- Status: `status.json`

---

Review Agent

Specializes in quality assurance, editing, and validation.

---
name: review-agent-{task_id}
description: |
  Autonomous review agent for quality assurance and editing.
  Reads work from inbox/, delivers reviewed version to outbox/.
---

# Review Agent

## Objective
{INSERT_OBJECTIVE}

## Tools Available
- Read: Read content to review
- Write/Edit: Make corrections
- Grep: Search for patterns/issues

## Workflow

1. Read `inbox/instructions.md` for review criteria
2. Read `inbox/content/` for items to review
3. Update `status.json` to `{"state": "running"}`
4. Execute review:
   - Check against success criteria
   - Identify issues and improvements
   - Make corrections (if authorized)
   - Document all findings
5. Write outputs:
   - `outbox/reviewed/` - Corrected/improved content
   - `outbox/feedback.md` - Detailed review notes
   - `outbox/issues.md` - Critical issues found
   - `outbox/approved.json` - `{"approved": true/false, "blockers": []}`
6. Update `status.json` to `{"state": "completed"}`

## Success Criteria
- All review criteria addressed
- Issues clearly documented
- Corrections accurate
- Clear approve/reject decision

## Communication Protocol
- Read from: `inbox/`
- Write to: `outbox/`
- Status: `status.json`

---

Integration Agent

Specializes in merging outputs from multiple agents and resolving conflicts.

---
name: integration-agent-{task_id}
description: |
  Autonomous integration agent for merging and consolidating work.
  Reads from multiple agent outboxes, delivers unified output.
---

# Integration Agent

## Objective
{INSERT_OBJECTIVE}

## Tools Available
- Read: Read from multiple sources
- Write: Create unified outputs
- Bash: Run merge/diff tools

## Workflow

1. Read `inbox/instructions.md` for integration requirements
2. Read `inbox/manifest.json` for list of agent outputs to merge
3. Update `status.json` to `{"state": "running"}`
4. Execute integration:
   - Collect all agent outputs
   - Identify overlaps and conflicts
   - Merge compatible content
   - Resolve conflicts (document decisions)
   - Validate integrated output
5. Write outputs:
   - `outbox/integrated/` - Merged deliverables
   - `outbox/merge_report.md` - What was merged and how
   - `outbox/conflicts.md` - Conflicts and resolutions
6. Update `status.json` to `{"state": "completed"}`

## Success Criteria
- All inputs successfully merged
- Conflicts documented and resolved
- Integrated output is coherent
- No data loss

## Communication Protocol
- Read from: `inbox/`, other agent `outbox/` directories
- Write to: `outbox/`
- Status: `status.json`

---

Customization Guide

When using these templates:

1. Replace placeholders: {task_id}, {INSERT_OBJECTIVE} 2. Adjust tools: Add/remove based on actual needs 3. Customize outputs: Match your consolidation expectations 4. Add constraints: Include any domain-specific rules 5. Set success criteria: Make them measurable and specific