@theihtisham/ai-agent-starter-kit 1.0.0

package/src/lib/agents/orchestration/debate.ts

@@ -0,0 +1,170 @@
+/**
+ * Debate Orchestrator — Agents discuss a topic, moderator synthesizes final answer.
+ *
+ * Multiple agents present their views on the same topic across rounds,
+ * then a moderator agent synthesizes the discussion into a final answer.
+ *
+ * Example: Three analysts debate market strategy, moderator picks the best approach.
+ */
+
+import type {
+  AgentConfig,
+  AgentMessage,
+  OrchestrationResult,
+  OrchestratorOptions,
+} from './types';
+
+export interface DebateOptions extends OrchestratorOptions {
+  /** Number of debate rounds (default: 2) */
+  rounds?: number;
+  /** The moderator agent that synthesizes the final answer */
+  moderator: AgentConfig;
+}
+
+export class DebateOrchestrator {
+  private agents: AgentConfig[];
+  private debateOptions: DebateOptions;
+
+  constructor(agents: AgentConfig[], options: DebateOptions) {
+    if (agents.length === 0) {
+      throw new Error('DebateOrchestrator requires at least one debating agent');
+    }
+    if (!options.moderator) {
+      throw new Error('DebateOrchestrator requires a moderator agent');
+    }
+    this.agents = agents;
+    this.debateOptions = {
+      rounds: 2,
+      timeoutMs: 120_000,
+      maxRetries: 1,
+      ...options,
+    };
+  }
+
+  /**
+   * Run a debate across multiple rounds, then have the moderator synthesize.
+   */
+  async run(topic: string): Promise<OrchestrationResult> {
+    const startTime = Date.now();
+    const trace: AgentMessage[] = [];
+    const rounds = this.debateOptions.rounds ?? 2;
+    const timeoutMs = this.debateOptions.timeoutMs ?? 120_000;
+
+    try {
+      const debateHistory: string[] = [];
+      let roundPrompt = `Topic: ${topic}\n\nPlease present your analysis and perspective on this topic.`;
+
+      // Run debate rounds
+      for (let round = 0; round < rounds; round++) {
+        if (Date.now() - startTime > timeoutMs) {
+          return {
+            content: 'Debate timed out.',
+            agentIds: this.agents.map((a) => a.id),
+            trace,
+            durationMs: Date.now() - startTime,
+            success: false,
+            error: `Timeout after ${timeoutMs}ms`,
+          };
+        }
+
+        const roundMessages: string[] = [];
+
+        for (const agent of this.agents) {
+          const inputMessage: AgentMessage = {
+            content: roundPrompt,
+            fromAgent: round === 0 ? 'user' : 'debate',
+            toAgent: agent.id,
+            metadata: { round: round + 1, topic },
+            timestamp: Date.now(),
+          };
+
+          try {
+            const maxRetries = this.debateOptions.maxRetries ?? 1;
+            let result: AgentMessage | undefined;
+
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+              try {
+                result = await agent.execute(inputMessage, agent);
+                break;
+              } catch (err) {
+                if (attempt >= maxRetries) {
+                  result = {
+                    content: `[Agent "${agent.name}" encountered an error: ${(err as Error).message}]`,
+                    fromAgent: agent.id,
+                    timestamp: Date.now(),
+                  };
+                }
+              }
+            }
+
+            trace.push(inputMessage);
+            trace.push(result!);
+            this.debateOptions.onAgentMessage?.(result!);
+
+            roundMessages.push(`**${agent.name}** (Round ${round + 1}):\n${result!.content}`);
+            debateHistory.push(`[${agent.name} — Round ${round + 1}]: ${result!.content}`);
+          } catch (err) {
+            const errorMsg = `[Agent "${agent.name}" failed: ${(err as Error).message}]`;
+            roundMessages.push(errorMsg);
+            debateHistory.push(errorMsg);
+          }
+        }
+
+        // Build prompt for next round incorporating previous responses
+        if (round < rounds - 1) {
+          roundPrompt = [
+            `Topic: ${topic}`,
+            '',
+            `Previous round responses:`,
+            ...roundMessages,
+            '',
+            'Consider the above perspectives. You may revise your position, address counterarguments, or strengthen your points.',
+          ].join('\n');
+        }
+      }
+
+      // Moderator synthesis
+      const moderatorPrompt = [
+        `You are moderating a debate on the following topic: "${topic}"`,
+        '',
+        `Here is the complete debate history:`,
+        ...debateHistory.map((h, i) => `${i + 1}. ${h}`),
+        '',
+        'Please synthesize the key points, areas of agreement and disagreement, and provide a balanced final conclusion.',
+      ].join('\n');
+
+      const moderatorInput: AgentMessage = {
+        content: moderatorPrompt,
+        fromAgent: 'debate',
+        toAgent: this.debateOptions.moderator.id,
+        metadata: { role: 'moderator', topic, rounds },
+        timestamp: Date.now(),
+      };
+
+      const moderatorResult = await this.debateOptions.moderator.execute(
+        moderatorInput,
+        this.debateOptions.moderator,
+      );
+
+      trace.push(moderatorInput);
+      trace.push(moderatorResult);
+
+      return {
+        content: moderatorResult.content,
+        agentIds: [...this.agents.map((a) => a.id), this.debateOptions.moderator.id],
+        trace,
+        durationMs: Date.now() - startTime,
+        success: true,
+      };
+    } catch (err) {
+      return {
+        content: '',
+        agentIds: [],
+        trace,
+        durationMs: Date.now() - startTime,
+        success: false,
+        error: (err as Error).message,
+      };
+    }
+  }
+}

package/src/lib/agents/orchestration/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Multi-Agent Orchestration -- Factory and re-exports.
+ *
+ * Provides a factory function to create orchestrators by pattern name,
+ * plus re-exports of all orchestrator classes.
+ */
+
+import type {
+  AgentConfig,
+  OrchestrationPattern,
+  OrchestrationResult,
+  OrchestratorOptions,
+  RouterClassifier,
+} from './types';
+import { SequentialOrchestrator } from './sequential';
+import { ParallelOrchestrator } from './parallel';
+import { RouterOrchestrator, keywordClassifier } from './router';
+import { DebateOrchestrator } from './debate';
+
+export { SequentialOrchestrator } from './sequential';
+export { ParallelOrchestrator } from './parallel';
+export { RouterOrchestrator, keywordClassifier } from './router';
+export { DebateOrchestrator } from './debate';
+export type { DebateOptions } from './debate';
+export type {
+  AgentConfig as OrchestrationAgentConfig,
+  AgentMessage,
+  Handoff,
+  OrchestrationPattern,
+  OrchestrationResult,
+  OrchestratorOptions,
+  RouterClassifier,
+} from './types';
+
+export interface CreateOrchestratorOptions extends OrchestratorOptions {
+  /** Required for 'router' pattern -- the classifier function */
+  classifier?: RouterClassifier;
+  /** Required for 'debate' pattern -- the moderator agent */
+  moderator?: AgentConfig;
+  /** Number of debate rounds (default: 2, only for 'debate' pattern) */
+  rounds?: number;
+}
+
+interface IOrchestrator {
+  run(input: string): Promise<OrchestrationResult>;
+}
+
+type AnyOrchestrator = IOrchestrator;
+
+/**
+ * Factory function -- create an orchestrator by pattern name.
+ *
+ * @example
+ * ```ts
+ * const orchestrator = createOrchestrator('sequential', agents);
+ * const result = await orchestrator.run("Analyze this data");
+ * ```
+ */
+export function createOrchestrator(
+  pattern: OrchestrationPattern,
+  agents: AgentConfig[],
+  options: CreateOrchestratorOptions = {},
+): AnyOrchestrator {
+  switch (pattern) {
+    case 'sequential':
+      return new SequentialOrchestrator(agents, options);
+
+    case 'parallel':
+      return new ParallelOrchestrator(agents, options);
+
+    case 'router': {
+      const classifier = options.classifier ?? keywordClassifier();
+      return new RouterOrchestrator(agents, classifier, options);
+    }
+
+    case 'debate': {
+      if (!options.moderator) {
+        throw new Error('Debate pattern requires a moderator agent in options.moderator');
+      }
+      return new DebateOrchestrator(agents, {
+        ...options,
+        moderator: options.moderator,
+        rounds: options.rounds,
+      });
+    }
+
+    default:
+      throw new Error(`Unknown orchestration pattern: ${pattern}`);
+  }
+}
+
+/**
+ * Quick helper -- run a pattern with agents and input in one call.
+ */
+export async function orchestrate(
+  pattern: OrchestrationPattern,
+  agents: AgentConfig[],
+  input: string,
+  options: CreateOrchestratorOptions = {},
+): Promise<OrchestrationResult> {
+  const orchestrator = createOrchestrator(pattern, agents, options);
+  return orchestrator.run(input);
+}

package/src/lib/agents/orchestration/parallel.ts

@@ -0,0 +1,143 @@
+/**
+ * Parallel Orchestrator — Runs multiple agents simultaneously.
+ *
+ * All agents receive the same input, and their results are merged.
+ * Useful for getting multiple perspectives or running independent analyses.
+ *
+ * Example: Sentiment Agent + Facts Agent + Grammar Agent all process the same text
+ */
+
+import type {
+  AgentConfig,
+  AgentMessage,
+  OrchestrationResult,
+  OrchestratorOptions,
+} from './types';
+
+export class ParallelOrchestrator {
+  private agents: AgentConfig[];
+  private options: OrchestratorOptions;
+
+  constructor(agents: AgentConfig[], options: OrchestratorOptions = {}) {
+    if (agents.length === 0) {
+      throw new Error('ParallelOrchestrator requires at least one agent');
+    }
+    this.agents = agents;
+    this.options = {
+      timeoutMs: 60_000,
+      maxRetries: 1,
+      ...options,
+    };
+  }
+
+  /**
+   * Run all agents in parallel and merge their results.
+   * The merged output combines all agent responses, labeled by agent name.
+   */
+  async run(input: string): Promise<OrchestrationResult> {
+    const startTime = Date.now();
+    const trace: AgentMessage[] = [];
+    const timeoutMs = this.options.timeoutMs ?? 60_000;
+
+    const inputMessage: AgentMessage = {
+      content: input,
+      fromAgent: 'user',
+      timestamp: Date.now(),
+    };
+
+    try {
+      // Execute all agents concurrently with a timeout
+      const results = await Promise.allSettled(
+        this.agents.map(async (agent) => {
+          const maxRetries = this.options.maxRetries ?? 1;
+          let lastError: Error | undefined;
+
+          for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+              const result = await agent.execute(inputMessage, agent);
+              this.options.onAgentMessage?.(result);
+              return { agent, result };
+            } catch (err) {
+              lastError = err as Error;
+              if (attempt < maxRetries) {
+                await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
+              }
+            }
+          }
+
+          return {
+            agent,
+            result: {
+              content: `[Error: Agent "${agent.name}" failed — ${lastError?.message}]`,
+              fromAgent: agent.id,
+              timestamp: Date.now(),
+            } satisfies AgentMessage,
+          };
+        }),
+      );
+
+      // Process results
+      const successfulResults: Array<{ agent: AgentConfig; result: AgentMessage }> = [];
+      const errors: string[] = [];
+
+      for (const settled of results) {
+        if (settled.status === 'fulfilled') {
+          successfulResults.push(settled.value);
+          trace.push(settled.value.result);
+        } else {
+          errors.push(settled.reason?.message ?? 'Unknown error');
+        }
+      }
+
+      // Check if we got any results
+      if (successfulResults.length === 0) {
+        return {
+          content: 'All agents failed to produce results.',
+          agentIds: this.agents.map((a) => a.id),
+          trace,
+          durationMs: Date.now() - startTime,
+          success: false,
+          error: errors.join('; '),
+        };
+      }
+
+      // Merge results into a single response
+      const mergedContent = this.mergeResults(successfulResults);
+
+      return {
+        content: mergedContent,
+        agentIds: successfulResults.map((r) => r.agent.id),
+        trace,
+        durationMs: Date.now() - startTime,
+        success: errors.length === 0,
+        error: errors.length > 0 ? `Partial failures: ${errors.join('; ')}` : undefined,
+      };
+    } catch (err) {
+      return {
+        content: '',
+        agentIds: [],
+        trace,
+        durationMs: Date.now() - startTime,
+        success: false,
+        error: (err as Error).message,
+      };
+    }
+  }
+
+  /**
+   * Merge results from all agents into a single coherent response.
+   */
+  private mergeResults(
+    results: Array<{ agent: AgentConfig; result: AgentMessage }>,
+  ): string {
+    if (results.length === 1) {
+      return results[0]!.result.content;
+    }
+
+    const sections = results.map(({ agent, result }) => {
+      return `### ${agent.name}\n${result.content}`;
+    });
+
+    return `## Combined Analysis\n\n${sections.join('\n\n---\n\n')}`;
+  }
+}

package/src/lib/agents/orchestration/router.ts

@@ -0,0 +1,199 @@
+/**
+ * Router Orchestrator — Uses a classifier to route tasks to the best agent.
+ *
+ * Analyzes the input to determine which agent (or agents) is best suited
+ * to handle the request. Supports both single-agent routing and
+ * multi-agent fan-out.
+ *
+ * Example: Route coding questions to CodeAgent, math to CalculatorAgent, etc.
+ */
+
+import type {
+  AgentConfig,
+  AgentMessage,
+  OrchestrationResult,
+  OrchestratorOptions,
+  RouterClassifier,
+} from './types';
+
+export class RouterOrchestrator {
+  private agents: AgentConfig[];
+  private classifier: RouterClassifier;
+  private options: OrchestratorOptions;
+
+  constructor(
+    agents: AgentConfig[],
+    classifier: RouterClassifier,
+    options: OrchestratorOptions = {},
+  ) {
+    if (agents.length === 0) {
+      throw new Error('RouterOrchestrator requires at least one agent');
+    }
+    this.agents = agents;
+    this.classifier = classifier;
+    this.options = {
+      timeoutMs: 60_000,
+      maxRetries: 2,
+      ...options,
+    };
+  }
+
+  /**
+   * Route the input to the best agent(s) and execute.
+   * If multiple agents are selected by the classifier, they run in parallel.
+   */
+  async run(input: string): Promise<OrchestrationResult> {
+    const startTime = Date.now();
+    const trace: AgentMessage[] = [];
+
+    try {
+      // Step 1: Classify the input to select the best agent(s)
+      const selected = await this.classifier(input, this.agents);
+      const selectedAgents = Array.isArray(selected) ? selected : [selected];
+
+      if (selectedAgents.length === 0) {
+        return {
+          content: 'No suitable agent found for this request.',
+          agentIds: [],
+          trace,
+          durationMs: Date.now() - startTime,
+          success: false,
+          error: 'Classifier returned no agents',
+        };
+      }
+
+      // Step 2: Execute selected agent(s)
+      const inputMessage: AgentMessage = {
+        content: input,
+        fromAgent: 'user',
+        timestamp: Date.now(),
+      };
+
+      if (selectedAgents.length === 1) {
+        // Single agent — execute directly
+        const agent = selectedAgents[0]!;
+        const result = await this.executeWithRetries(agent, inputMessage);
+        trace.push(inputMessage);
+        trace.push(result);
+
+        return {
+          content: result.content,
+          agentIds: [agent.id],
+          trace,
+          durationMs: Date.now() - startTime,
+          success: true,
+        };
+      }
+
+      // Multiple agents — execute in parallel
+      const results = await Promise.allSettled(
+        selectedAgents.map(async (agent) => {
+          const result = await this.executeWithRetries(agent, inputMessage);
+          this.options.onAgentMessage?.(result);
+          return { agent, result };
+        }),
+      );
+
+      const successfulResults: Array<{ agent: AgentConfig; result: AgentMessage }> = [];
+      for (const settled of results) {
+        if (settled.status === 'fulfilled') {
+          successfulResults.push(settled.value);
+          trace.push(settled.value.result);
+        }
+      }
+
+      if (successfulResults.length === 0) {
+        return {
+          content: 'All selected agents failed.',
+          agentIds: selectedAgents.map((a) => a.id),
+          trace,
+          durationMs: Date.now() - startTime,
+          success: false,
+          error: 'All agents failed',
+        };
+      }
+
+      // Merge multiple results
+      const merged =
+        successfulResults.length === 1
+          ? successfulResults[0]!.result.content
+          : successfulResults
+              .map(({ agent, result }) => `**${agent.name}**: ${result.content}`)
+              .join('\n\n');
+
+      return {
+        content: merged,
+        agentIds: successfulResults.map((r) => r.agent.id),
+        trace,
+        durationMs: Date.now() - startTime,
+        success: true,
+      };
+    } catch (err) {
+      return {
+        content: '',
+        agentIds: [],
+        trace,
+        durationMs: Date.now() - startTime,
+        success: false,
+        error: (err as Error).message,
+      };
+    }
+  }
+
+  /** Execute an agent with retry logic */
+  private async executeWithRetries(
+    agent: AgentConfig,
+    input: AgentMessage,
+  ): Promise<AgentMessage> {
+    const maxRetries = this.options.maxRetries ?? 2;
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await agent.execute(input, agent);
+      } catch (err) {
+        lastError = err as Error;
+        if (attempt < maxRetries) {
+          await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
+        }
+      }
+    }
+
+    throw lastError ?? new Error(`Agent "${agent.name}" failed`);
+  }
+}
+
+/**
+ * Built-in keyword-based classifier for simple routing.
+ * Matches input keywords to agent descriptions and names.
+ */
+export function keywordClassifier(): RouterClassifier {
+  return async (input: string, agents: AgentConfig[]) => {
+    const inputLower = input.toLowerCase();
+    const scored = agents.map((agent) => {
+      const descLower = agent.description.toLowerCase();
+      const nameLower = agent.name.toLowerCase();
+      const keywords = [...descLower.split(/\s+/), ...nameLower.split(/\s+/)];
+
+      let score = 0;
+      for (const keyword of keywords) {
+        if (keyword.length < 3) continue;
+        if (inputLower.includes(keyword)) {
+          score += 1;
+        }
+      }
+      return { agent, score };
+    });
+
+    scored.sort((a, b) => b.score - a.score);
+
+    // Return top agent if it scored above threshold
+    const best = scored[0];
+    if (best && best.score > 0) {
+      return best.agent;
+    }
+
+    // Fallback to first agent
+    return agents[0]!;
+  };
+}