agentic-orchestration · diff
v1.0.0 to v1.0.0
3 added, 277 removed. Audit A to A.
---
name: agentic-orchestration
description: Patterns for multi-agent coordination, task decomposition, handoffs, and workflow orchestration. Use when designing or debugging agent systems, splitting a large task across sub-agents, defining handoff contracts, or choosing an orchestration topology.
version: 1.0.0
last_updated: 2025-12-19
external_version: "Claude Agent SDK 2025"
changelog: |
- 1.0.0: Initial skill with orchestration patterns from Claude Agent SDK and FrankX system
---
# Agentic Orchestration Patterns
This skill covers patterns for coordinating multiple AI agents, decomposing complex tasks, managing handoffs, and building robust agent workflows.
---
## Orchestration Fundamentals
### Agent Hierarchy Model
```
┌─────────────────────────────────────────────────────┐
│ ORCHESTRATOR AGENT │
│ (Strategic coordination, task routing, synthesis) │
├─────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Specialist │ │ Specialist │ │ Specialist │ │
│ │ Agent A │ │ Agent B │ │ Agent C │ │
│ │ (Domain 1) │ │ (Domain 2) │ │ (Domain 3) │ │
│ └──────────────┘ └──────────────┘ └────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
```
### Core Principles
1. **Single Responsibility**: Each agent has one clear domain
2. **Explicit Handoffs**: Clear protocols for transferring work
3. **Context Preservation**: State travels with the task
4. **Graceful Degradation**: System works if agents fail
5. **Observable Execution**: Can see what each agent is doing
---
## Task Decomposition Patterns
### Pattern 1: Hierarchical Decomposition
```
Complex Task: "Build a feature for user authentication"
Decomposed:
├── Research Phase (Research Agent)
│ ├── Analyze existing auth patterns in codebase
│ ├── Identify dependencies and constraints
│ └── Document findings
│
├── Design Phase (Architect Agent)
│ ├── Design auth flow
│ ├── Define API contracts
│ └── Create component structure
│
├── Implementation Phase (Developer Agent)
│ ├── Implement backend auth logic
│ ├── Build frontend components
│ └── Add error handling
│
├── Testing Phase (QA Agent)
│ ├── Write unit tests
│ ├── Integration tests
│ └── Security review
│
└── Documentation Phase (Docs Agent)
├── API documentation
├── User guide
└── Developer notes
```
### Pattern 2: Parallel Decomposition
```
Task: "Analyze codebase and suggest improvements"
Parallel Execution:
┌─────────────────────────────────────────────────────┐
│ ORCHESTRATOR │
│ Spawns parallel agents │
└───────────┬─────────────┬─────────────┬────────────┘
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Security │ │Performance│ │ Code │
│ Analyst │ │ Analyst │ │ Quality │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
▼ ▼ ▼
[Security [Performance [Quality
Report] Report] Report]
│ │ │
└──────────────┼──────────────┘
│
▼
┌─────────────────┐
│ ORCHESTRATOR │
│ Synthesizes │
└─────────────────┘
```
### Pattern 3: Iterative Refinement
```
Task: "Write a technical blog post"
Iteration Loop:
1. Researcher → Gathers information
2. Writer → Creates draft
3. Editor → Reviews and critiques
4. Writer → Revises based on feedback
5. Editor → Approves or requests more changes
6. Repeat 4-5 until quality threshold met
7. Publisher → Formats and publishes
```
---
## Handoff Patterns
### Pattern 1: Explicit Handoff Protocol
```typescript
interface TaskHandoff {
from_agent: string;
to_agent: string;
task_id: string;
context: {
original_request: string;
work_completed: string[];
current_state: any;
next_steps: string[];
};
artifacts: {
files_created: string[];
files_modified: string[];
decisions_made: Decision[];
};
}
// Example handoff
const handoff: TaskHandoff = {
from_agent: "ArchitectAgent",
to_agent: "DeveloperAgent",
task_id: "auth-feature-123",
context: {
original_request: "Implement user authentication",
work_completed: [
"Analyzed existing patterns",
"Designed auth flow",
"Created API contracts"
],
current_state: {
design_doc: "/docs/auth-design.md",
api_spec: "/specs/auth-api.yaml"
},
next_steps: [
"Implement AuthService class",
"Create login/logout endpoints",
"Build session management"
]
},
artifacts: {
files_created: ["/docs/auth-design.md", "/specs/auth-api.yaml"],
files_modified: [],
decisions_made: [
{ decision: "Use JWT for tokens", rationale: "Stateless, scalable" },
{ decision: "Redis for session store", rationale: "Fast, supports TTL" }
]
}
};
```
### Pattern 2: Capability-Based Routing
```typescript
const agentCapabilities = {
ResearchAgent: ["search", "analyze", "summarize", "compare"],
ArchitectAgent: ["design", "plan", "structure", "evaluate"],
DeveloperAgent: ["implement", "refactor", "debug", "optimize"],
ReviewerAgent: ["review", "critique", "validate", "approve"],
DocsAgent: ["document", "explain", "format", "publish"]
};
function routeTask(task: string): string {
const taskVerb = extractVerb(task);
for (const [agent, capabilities] of Object.entries(agentCapabilities)) {
if (capabilities.includes(taskVerb)) {
return agent;
}
}
return "GeneralAgent"; // Fallback
}
```
### Pattern 3: Context Window Management
```typescript
// Problem: Context grows as agents work
// Solution: Summarize and compress at handoffs
interface CompressedContext {
essential: {
task_goal: string;
key_decisions: string[];
current_blockers: string[];
};
reference: {
file_paths: string[]; // Can be re-read if needed
doc_links: string[]; // External references
};
discarded: {
exploration_notes: string; // Summarized, not full content
rejected_approaches: string[];
};
}
function compressForHandoff(fullContext: any): CompressedContext {
return {
essential: extractEssentials(fullContext),
reference: extractReferences(fullContext),
discarded: summarizeDiscarded(fullContext)
};
}
```
---
- ## Coordination Patterns
- ### Pattern 1: Conductor Model
- ```
- One orchestrator coordinates all activity:
-
- ┌─────────────────────────────────────────────┐
- │ CONDUCTOR AGENT │
- │ - Receives initial request │
- │ - Decomposes into subtasks │
- │ - Assigns to specialist agents │
- │ - Monitors progress │
- │ - Synthesizes results │
- │ - Handles failures and retries │
- └─────────────────────────────────────────────┘
-
- Best for: Complex projects with many dependencies
- Example: FrankX Starlight Orchestrator
- ```
-
- ### Pattern 2: Pipeline Model
- ```
- Sequential processing through specialized stages:
-
- Request → [Agent A] → [Agent B] → [Agent C] → Result
- │ │ │
- Stage 1 Stage 2 Stage 3
- Research Design Execute
-
- Best for: Well-defined workflows with clear stages
- Example: Content creation pipeline
- ```
-
- ### Pattern 3: Swarm Model
- ```
- Multiple agents work in parallel, coordinating peer-to-peer:
-
- ┌────────┐
- │Agent A │←──────────────────┐
- └───┬────┘ │
- │ │
- ┌────▼────┐ ┌────┴───┐
- │ Agent B │◄────────────►│Agent D │
- └────┬────┘ └────┬───┘
- │ │
- ┌───▼────┐ │
- │Agent C │◄──────────────────┘
- └────────┘
-
- Best for: Exploratory tasks, parallel research
- Example: Codebase analysis from multiple angles
- ```
-
- ### Pattern 4: Blackboard Model
- ```
- Shared workspace that all agents read/write:
-
- ┌─────────────────────────────────────────┐
- │ BLACKBOARD │
- │ ┌─────────────────────────────────┐ │
- │ │ Current State: { ... } │ │
- │ │ Hypotheses: [ ... ] │ │
- │ │ Evidence: [ ... ] │ │
- │ │ Conclusions: [ ... ] │ │
- │ └─────────────────────────────────┘ │
- └─────────────────────────────────────────┘
- │ │ │
- ┌────▼───┐ ┌────▼───┐ ┌────▼───┐
- │Agent A │ │Agent B │ │Agent C │
- │ reads │ │ reads │ │ reads │
- │ writes │ │ writes │ │ writes │
- └────────┘ └────────┘ └────────┘
-
- Best for: Complex problem-solving with evolving understanding
- Example: Debugging a complex system issue
- ```
-
- ---
-
- ## Error Handling & Recovery
-
- ### Pattern 1: Retry with Backoff
- ```typescript
- async function executeWithRetry(agent, task, maxRetries = 3) {
- for (let attempt = 1; attempt <= maxRetries; attempt++) {
- try {
- return await agent.execute(task);
- } catch (error) {
- if (attempt === maxRetries) throw error;
-
- const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
- console.log(`Attempt ${attempt} failed, retrying in ${delay}ms`);
- await sleep(delay);
- }
- }
- }
- ```
-
- ### Pattern 2: Fallback Agents
- ```typescript
- const agentFallbacks = {
- "SpecialistCodeReviewer": ["GeneralCodeReviewer", "SeniorDeveloper"],
- "SecurityAnalyst": ["GeneralAnalyst", "SeniorDeveloper"],
- "PerformanceExpert": ["GeneralAnalyst", "SeniorDeveloper"]
- };
-
- async function executeWithFallback(primaryAgent, task) {
- try {
- return await primaryAgent.execute(task);
- } catch (error) {
- const fallbacks = agentFallbacks[primaryAgent.name] || [];
-
- for (const fallbackName of fallbacks) {
- try {
- console.log(`Primary failed, trying ${fallbackName}`);
- return await getAgent(fallbackName).execute(task);
- } catch (fallbackError) {
- continue;
- }
- }
-
- throw new Error(`All agents failed for task: ${task.id}`);
- }
- }
- ```
-
- ### Pattern 3: Checkpoint & Resume
- ```typescript
- interface Checkpoint {
- task_id: string;
- completed_steps: string[];
- current_step: string;
- state: any;
- timestamp: Date;
- }
-
- async function executeWithCheckpoints(task, steps) {
- const checkpoint = await loadCheckpoint(task.id);
- const startIndex = checkpoint
- ? steps.indexOf(checkpoint.current_step)
- : 0;
-
- for (let i = startIndex; i < steps.length; i++) {
- const step = steps[i];
-
- try {
- await executeStep(step, task);
- await saveCheckpoint({
- task_id: task.id,
- completed_steps: steps.slice(0, i + 1),
- current_step: steps[i + 1] || "complete",
- state: task.state,
- timestamp: new Date()
- });
- } catch (error) {
- // Checkpoint is saved, can resume from here
- throw error;
- }
- }
- }
- ```
-
- ---
-
- ## Observability Patterns
-
- ### Pattern 1: Structured Logging
- ```typescript
- function agentLog(agent, event, details) {
- console.log(JSON.stringify({
- timestamp: new Date().toISOString(),
- agent: agent.name,
- task_id: agent.currentTask?.id,
- event: event,
- details: details,
- duration_ms: details.duration,
- tokens_used: details.tokens
- }));
- }
-
- // Usage
- agentLog(agent, "TASK_START", { task: task.description });
- agentLog(agent, "TOOL_CALL", { tool: "read_file", path: "/src/index.ts" });
- agentLog(agent, "TASK_COMPLETE", { result: "success", duration: 5230 });
- ```
-
- ### Pattern 2: Progress Tracking
- ```typescript
- interface TaskProgress {
- task_id: string;
- total_steps: number;
- completed_steps: number;
- current_step: string;
- estimated_remaining: number; // seconds
- agents_involved: string[];
- }
-
- // Expose progress for UI/monitoring
- function getProgress(task): TaskProgress {
- return {
- task_id: task.id,
- total_steps: task.steps.length,
- completed_steps: task.completedSteps.length,
- current_step: task.currentStep?.description || "idle",
- estimated_remaining: estimateRemaining(task),
- agents_involved: task.agentHistory
- };
- }
- ```
-
- ### Pattern 3: Decision Audit Trail
- ```typescript
- interface Decision {
- timestamp: Date;
- agent: string;
- decision: string;
- options_considered: string[];
- rationale: string;
- confidence: number; // 0-1
- reversible: boolean;
- }
-
- // Track all significant decisions
- const decisionLog: Decision[] = [];
-
- function recordDecision(agent, decision, options, rationale, confidence) {
- decisionLog.push({
- timestamp: new Date(),
- agent: agent.name,
- decision,
- options_considered: options,
- rationale,
- confidence,
- reversible: true
- });
- }
- ```
-
- ---
-
- ## FrankX System Application
-
- ### Starlight Orchestrator Pattern
- ```
- The FrankX system uses weighted synthesis:
-
- ┌────────────────────────────────────────────────────┐
- │ STARLIGHT ORCHESTRATOR │
- │ (Meta-intelligence coordinator) │
- ├────────────────────────────────────────────────────┤
- │ │
- │ Specialist Domains: │
- │ ├── Starlight Architect (Systems design) │
- │ ├── Creation Engine (Content/product) │
- │ ├── Visionary (Future strategy) │
- │ └── Sonic Engineer (Music/audio) │
- │ │
- │ Synthesis Process: │
- │ 1. Each agent provides perspective │
- │ 2. Orchestrator weights by domain relevance │
- │ 3. Conflicts are explicitly surfaced │
- │ 4. Final recommendation synthesizes all views │
- │ │
- └────────────────────────────────────────────────────┘
- ```
+ ## Reference
- ### Agent Team Patterns in FrankX
- **Book Writing Team:**
- - Master Story Architect → Design
- - Genre Writer → Draft
- - Editor → Review cycles
- - Sensitivity Reader → Final check
- - Continuity Guardian → Consistency
+ The full detail lives in `references/` and loads only when needed:
- **Arcanea Development Team:**
- - Architect → Design
- - Frontend Specialist → UI
- - Backend Specialist → API
- - AI Specialist → Luminor integration
- - DevOps → Deployment
+ - [`references/advanced-patterns.md`](references/advanced-patterns.md) — coordination, error handling, observability & system application patterns.
---
## Anti-Patterns to Avoid
### ❌ God Agent
One agent that does everything - no specialization, no delegation.
### ❌ Agent Explosion
Too many tiny agents with overlapping responsibilities.
### ❌ Lost Context
Handoffs that don't preserve essential information.
### ❌ Infinite Loops
Agents that keep handing work back and forth.
### ❌ Silent Failures
Agents that fail without proper error reporting.
### ❌ Unobservable Execution
Can't see what agents are doing or why.
---
*Good orchestration is invisible - the system should feel like one coherent intelligence, not a committee of bickering agents.*