multi-agent-orchestration git:20260728.80a7ab6A

Immutable. This exact content is served forever at /api/v1/blob/b04605b52580dde8.

---
name: multi-agent-orchestration
description: "Coordinate multiple AI agents for complex tasks — decomposition, delegation, and synthesis"
lastReviewed: 2026-04-30
---

# Multi-Agent Orchestration Skill


> Decompose complex problems into agent-appropriate subtasks, delegate effectively, and synthesize results.

## ⚠️ Rapid Evolution Domain

Multi-agent patterns are evolving rapidly. This skill captures stable patterns while acknowledging the field is in flux.

**Refresh triggers:**

- New orchestration frameworks (LangGraph, AutoGen, CrewAI releases)
- Claude/GPT native multi-agent features
- VS Code Copilot agent architecture changes

**Last validated:** February 2026

---

## Core Concepts

### When to Use Multi-Agent

| Scenario | Single Agent | Multi-Agent |
|----------|--------------|-------------|
| Simple code edit | ✅ | ❌ Overkill |
| Multi-file refactor | ✅ (if capable model) | ⚠️ Consider |
| Research + implement | ⚠️ Long context | ✅ Decompose |
| Cross-domain task | ❌ Context overload | ✅ Specialists |
| Parallel independent work | ❌ Sequential | ✅ Parallel agents |

### Agent Roles

| Role | Responsibility | Example |
|------|---------------|---------|
| **Orchestrator** | Decompose, delegate, synthesize | Main chat session |
| **Specialist** | Deep expertise in one domain | Security reviewer agent |
| **Worker** | Execute well-defined subtask | "Find all usages of X" |
| **Critic** | Validate, review, improve | Code review agent |

---

## Decomposition Patterns

### 1. **Horizontal Decomposition** (Parallel)

Split task into independent subtasks that can run simultaneously.

```
┌─────────────────┐
│  Orchestrator   │
└───────┬─────────┘
        │ decompose
   ┌────┴────┬────────┐
   ▼         ▼        ▼
┌─────┐  ┌─────┐  ┌─────┐
│ A1  │  │ A2  │  │ A3  │   (parallel)
└──┬──┘  └──┬──┘  └──┬──┘
   └────────┼────────┘
            ▼
      synthesize
```

**When to use:**

- Tasks have no dependencies
- Results can be merged mechanically
- Time is critical

**Example:** "Search for security issues in auth, api, and database modules"

### 2. **Vertical Decomposition** (Pipeline)

Chain agents where each builds on previous output.

```
┌─────────────────┐
│  Orchestrator   │
└───────┬─────────┘
        ▼
    ┌───────┐
    │  A1   │ → research
    └───┬───┘
        ▼
    ┌───────┐
    │  A2   │ → analyze
    └───┬───┘
        ▼
    ┌───────┐
    │  A3   │ → implement
    └───────┘
```

**When to use:**

- Each step needs output from previous
- Context builds incrementally
- Quality gates between steps

**Example:** "Research best practices → Design API → Implement → Review"

### 3. **Hierarchical Decomposition** (Tree)

Orchestrator delegates to sub-orchestrators who manage workers.

```
┌─────────────────┐
│   Root Orch     │
└───────┬─────────┘
   ┌────┴────┐
   ▼         ▼
┌─────┐   ┌─────┐
│SubO1│   │SubO2│    (sub-orchestrators)
└──┬──┘   └──┬──┘
 ┌─┴─┐    ┌──┴──┐
 ▼   ▼    ▼     ▼
┌─┐ ┌─┐  ┌─┐   ┌─┐
│W│ │W│  │W│   │W│   (workers)
└─┘ └─┘  └─┘   └─┘
```

**When to use:**

- Very complex tasks
- Different domains within task
- Scale beyond single orchestrator's context

---

## Delegation Best Practices

### Crafting Agent Instructions

When delegating to a subagent, specify:

| Element | Purpose | Example |
|---------|---------|---------|
| **Context** | What they need to know | "Working on the AI assistant VS Code extension" |
| **Scope** | Clear boundaries | "Only look in /src/services" |
| **Output** | Expected format | "Return JSON with findings" |
| **Constraints** | What NOT to do | "Don't modify files, only report" |

### Template for Subagent Prompt

```
**Task:** [One-sentence objective]

**Context:**
- Project: [name/type]
- Relevant files: [list]
- What's already done: [state]

**Scope:**
- DO: [specific actions]
- DON'T: [boundaries]

**Expected Output:**
[Format and content expectations]

**Success Criteria:**
[How you'll know it's done right]
```

---

## Synthesis Patterns

### Merging Agent Outputs

| Pattern | When | How |
|---------|------|-----|
| **Concatenate** | Independent results | Simple append |
| **Deduplicate** | Overlapping searches | Hash/compare |
| **Vote** | Multiple opinions | Majority wins |
| **Synthesize** | Diverse perspectives | LLM summary |
| **Validate** | Critical decisions | Critic agent reviews |

### Conflict Resolution

When agents disagree:

1. **Identify conflict type**
   - Factual (check sources)
   - Opinion (escalate to user)
   - Interpretation (provide both views)

2. **Resolution strategies**
   - Ask clarifying questions
   - Request evidence from agents
   - Escalate to more capable model
   - Present options to user

---

## VS Code Copilot Patterns

### Using `runSubagent` Effectively

The `runSubagent` tool enables orchestration within VS Code:

```typescript
// Good: Clear task with expected output
await runSubagent({
  prompt: `Search the codebase for all error handling patterns.
           Return a JSON array of: {file, line, pattern, quality}`,
  description: "Find error patterns"
user-invokable: false
});

// Bad: Vague delegation
await runSubagent({
  prompt: "Look for problems in the code",  // Too vague
  description: "Find issues"
user-invokable: false
});
```

### When to Use Subagent vs Direct

| Scenario | Approach |
|----------|----------|
| Simple search | Direct `grep_search` |
| Complex multi-step search | `runSubagent` |
| Single file edit | Direct `replace_string_in_file` |
| Multi-file coordinated change | Consider subagent for planning |
| Research + implementation | Subagent for research, direct for implementation |

---

## Common Anti-Patterns

### ❌ Over-Orchestration

**Problem:** Using multiple agents for simple tasks
**Symptom:** Slower, more expensive, no quality gain
**Fix:** Trust capable models for multi-step tasks up to complexity threshold

### ❌ Insufficient Context

**Problem:** Agents lack needed information
**Symptom:** Repeated clarification requests, wrong assumptions
**Fix:** Front-load context in delegation prompt

### ❌ No Synthesis Strategy

**Problem:** Raw agent outputs dumped on user
**Symptom:** User must manually integrate results
**Fix:** Plan synthesis before decomposition

### ❌ Circular Dependencies

**Problem:** Agent A needs B's output, B needs A's output
**Symptom:** Deadlock or infinite loops
**Fix:** Identify and break cycles in task graph

---

## Framework Landscape (2026)

| Framework | Strength | Use Case |
|-----------|----------|----------|
| **LangGraph** | State machines, cycles | Complex workflows |
| **AutoGen** | Conversation patterns | Research, debate |
| **CrewAI** | Role-based teams | Business processes |
| **VS Code Agents** | IDE integration | Code tasks |
| **Semantic Kernel** | .NET native | Enterprise C# |

---

## the AI assistant-Specific Patterns

### Heir Orchestration

your AI assistant can coordinate heirs for cross-platform tasks:

```
your AI assistant (orchestrator)
├── VS Code Heir → code analysis
├── M365 Heir → document synthesis
└── Global Knowledge → pattern matching
```

### Skill Selection as Orchestration

When the AI assistant runs Skill Selection Optimization (SSO), it's a form of self-orchestration:

1. Survey available skills (agents)
2. Match to task requirements
3. Load relevant skills
4. Execute with combined expertise

---

## Implementation Checklist

When designing multi-agent workflows:

- [ ] Can a single capable model handle this?
- [ ] Are subtasks truly independent (or pipelined)?
- [ ] Is context sufficient for each agent?
- [ ] Is output format clearly specified?
- [ ] Is synthesis strategy defined?
- [ ] Are failure modes handled?
- [ ] Is the orchestration overhead justified?

---

## Related Skills

- **skill-selection-optimization** — Pre-task skill loading
- **prompt-engineering** — Crafting effective agent prompts
- **appropriate-reliance** — Knowing when to trust agent output
- **root-cause-analysis** — Debugging multi-agent failures

---

*Multi-agent orchestration is powerful but not always necessary. Start simple, add agents when complexity demands it.*