1# Orchestrator Agent
2 
3## Purpose
4 
5The Orchestrator Agent manages complex workflows by delegating tasks to specialized agents, coordinating their outputs, and ensuring coherent end-to-end execution. It serves as the primary interface for multi-agent operations.
6 
7## Agent Definition
8 
9```typescript
10import { ToolLoopAgent } from "ai";
11import { anthropic } from "@ai-sdk/anthropic";
12import { orchestrationTools } from "../tools";
13 
14export const orchestratorAgent = new ToolLoopAgent({
15  name: "orchestrator",
16  model: anthropic("claude-sonnet-4-20250514"),
17  instructions: `You are a workflow orchestration expert.
18 
19Your role is to:
201. Analyze complex tasks and break them into subtasks
212. Assign subtasks to appropriate specialized agents
223. Coordinate agent outputs and handle dependencies
234. Synthesize results into coherent final outputs
245. Handle errors and retries gracefully
25 
26Orchestration Principles:
27- Decompose tasks by capability requirements
28- Parallelize independent operations when possible
29- Maintain context continuity across agent handoffs
30- Validate intermediate outputs before proceeding
31- Provide clear status updates during long operations
32 
33Available Agents:
34- evaluator: Assesses quality of LLM outputs
35- researcher: Gathers and synthesizes information
36- writer: Generates and refines content
37- analyst: Performs data analysis and insights
38 
39When delegating:
40- Provide complete context the agent needs
41- Specify expected output format
42- Set clear success criteria`,
43  
44  tools: {
45    delegateToAgent: orchestrationTools.delegateToAgent,
46    parallelExecution: orchestrationTools.parallelExecution,
47    waitForCompletion: orchestrationTools.waitForCompletion,
48    synthesizeResults: orchestrationTools.synthesizeResults,
49    handleError: orchestrationTools.handleError
50  }
51});
52```
53 
54## Capabilities
55 
56### Task Delegation
57Route a task to a specialized agent.
58 
59**Input:**
60- Agent name
61- Task description
62- Context/dependencies
63- Expected output format
64 
65**Output:**
66- Agent response
67- Execution metadata
68- Status
69 
70### Parallel Execution
71Execute multiple independent tasks simultaneously.
72 
73**Input:**
74- List of (agent, task) pairs
75- Timeout configuration
76 
77**Output:**
78- Results array
79- Completion status per task
80- Any errors encountered
81 
82### Result Synthesis
83Combine outputs from multiple agents into coherent result.
84 
85**Input:**
86- Agent outputs
87- Synthesis instructions
88- Target format
89 
90**Output:**
91- Synthesized result
92- Source attribution
93- Confidence assessment
94 
95### Error Handling
96Manage failures and implement retry logic.
97 
98**Input:**
99- Failed task
100- Error details
101- Retry policy
102 
103**Output:**
104- Retry result or
105- Graceful degradation or
106- Error escalation
107 
108## Configuration
109 
110```typescript
111interface OrchestratorConfig {
112  // Execution settings
113  maxParallelTasks: number;
114  defaultTimeout: number; // ms
115  retryPolicy: RetryPolicy;
116  
117  // Quality settings
118  validateIntermediateOutputs: boolean;
119  evaluateBeforeDelivery: boolean;
120  
121  // Reporting
122  enableProgressUpdates: boolean;
123  updateFrequency: number; // ms
124}
125 
126interface RetryPolicy {
127  maxRetries: number;
128  backoffMultiplier: number;
129  retryableErrors: string[];
130}
131 
132const defaultConfig: OrchestratorConfig = {
133  maxParallelTasks: 5,
134  defaultTimeout: 60000,
135  retryPolicy: {
136    maxRetries: 3,
137    backoffMultiplier: 2,
138    retryableErrors: ["RATE_LIMIT", "TIMEOUT", "TEMPORARY_ERROR"]
139  },
140  validateIntermediateOutputs: true,
141  evaluateBeforeDelivery: false,
142  enableProgressUpdates: true,
143  updateFrequency: 5000
144};
145```
146 
147## Usage Example
148 
149```typescript
150import { orchestratorAgent } from "./agents/orchestrator-agent";
151 
152const result = await orchestratorAgent.generate({
153  prompt: `Complete the following research and analysis task:
154 
1551. Research current best practices for LLM evaluation
1562. Analyze the trade-offs between different evaluation methods
1573. Generate a recommendation report
1584. Evaluate the quality of the report
159 
160Ensure the final output is comprehensive but accessible to technical leaders.`
161});
162```
163 
164## Orchestration Patterns
165 
166### Sequential Pipeline
167```mermaid
168graph LR
169    A[Task] --> B[Research Agent]
170    B --> C[Analyst Agent]
171    C --> D[Writer Agent]
172    D --> E[Evaluator Agent]
173    E --> F[Final Output]
174```
175 
176### Parallel with Aggregation
177```mermaid
178graph TD
179    A[Task] --> B[Parallel Dispatch]
180    B --> C[Agent 1]
181    B --> D[Agent 2]
182    B --> E[Agent 3]
183    C --> F[Aggregation]
184    D --> F
185    E --> F
186    F --> G[Synthesis]
187```
188 
189### Iterative Refinement
190```mermaid
191graph TD
192    A[Draft] --> B[Evaluator]
193    B --> C{Score OK?}
194    C -->|No| D[Refine]
195    D --> A
196    C -->|Yes| E[Final Output]
197```
198 
199## Integration Points
200 
201- **API Gateway**: Primary entry point for complex requests
202- **Job Queue**: Handle long-running orchestrated tasks
203- **Monitoring**: Track multi-agent execution metrics
204- **Audit Log**: Record all delegations and decisions
205 
206