@agentforge/patterns 0.6.2 → 0.6.3

package/dist/index.cjs

@@ -1642,26 +1642,35 @@ var RoutingStrategySchema = import_zod7.z.enum([
 ]);
 var RoutingDecisionSchema = import_zod7.z.object({
   /**
-   * Target agent to route to
+   * Target agent to route to (single agent routing)
+   * @deprecated Use targetAgents for parallel routing support
    */
-  targetAgent: import_zod7.z.string().describe("Agent to route the task to"),
+  targetAgent: import_zod7.z.string().nullable().default(null).describe("Agent to route the task to (single routing)"),
+  /**
+   * Target agents to route to (parallel routing)
+   * When multiple agents are specified, they execute in parallel
+   */
+  targetAgents: import_zod7.z.array(import_zod7.z.string()).nullable().default(null).describe("Agents to route the task to (parallel routing)"),
   /**
    * Reasoning for the routing decision
    */
-  reasoning: import_zod7.z.string().optional().describe("Explanation for routing decision"),
+  reasoning: import_zod7.z.string().default("").describe("Explanation for routing decision"),
   /**
    * Confidence in the routing decision (0-1)
    */
-  confidence: import_zod7.z.number().min(0).max(1).optional().describe("Confidence score"),
+  confidence: import_zod7.z.number().min(0).max(1).default(0.8).describe("Confidence score"),
   /**
    * Strategy used for routing
    */
-  strategy: RoutingStrategySchema.describe("Strategy used for this decision"),
+  strategy: RoutingStrategySchema.default("llm-based").describe("Strategy used for this decision"),
   /**
    * Timestamp of the routing decision
    */
-  timestamp: import_zod7.z.number().optional().describe("Timestamp of the decision")
-});
+  timestamp: import_zod7.z.number().default(() => Date.now()).describe("Timestamp of the decision")
+}).refine(
+  (data) => data.targetAgent || data.targetAgents && data.targetAgents.length > 0,
+  { message: "Either targetAgent or targetAgents must be provided" }
+);
 var WorkerCapabilitiesSchema = import_zod7.z.object({
   /**
    * Skills/capabilities the agent has
@@ -1929,16 +1938,33 @@ var DEFAULT_SUPERVISOR_SYSTEM_PROMPT = `You are a supervisor agent responsible f
 Your job is to:
 1. Analyze the current task and context
 2. Review available worker capabilities
-3. Select the most appropriate worker for the task
+3. Select the most appropriate worker(s) for the task
 4. Provide clear reasoning for your decision
 
-Respond with a JSON object containing:
+**IMPORTANT: You can route to MULTIPLE workers for parallel execution when:**
+- The task requires information from multiple domains (e.g., code + documentation)
+- Multiple workers have complementary expertise
+- Parallel execution would provide a more comprehensive answer
+
+**Response Format:**
+
+For SINGLE worker routing:
 {
   "targetAgent": "worker_id",
   "reasoning": "explanation of why this worker is best suited",
   "confidence": 0.0-1.0,
   "strategy": "llm-based"
-}`;
+}
+
+For PARALLEL multi-worker routing:
+{
+  "targetAgents": ["worker_id_1", "worker_id_2", ...],
+  "reasoning": "explanation of why these workers should work in parallel",
+  "confidence": 0.0-1.0,
+  "strategy": "llm-based"
+}
+
+Choose parallel routing when the task benefits from multiple perspectives or data sources.`;
 var llmBasedRouting = {
   name: "llm-based",
   async route(state, config) {
@@ -1961,7 +1987,7 @@ var llmBasedRouting = {
 Available workers:
 ${workerInfo}
 
-Select the best worker for this task and explain your reasoning.`;
+Select the best worker(s) for this task and explain your reasoning.`;
     const conversationHistory = [];
     let attempt = 0;
     while (attempt < maxRetries) {
@@ -1983,19 +2009,33 @@ Select the best worker for this task and explain your reasoning.`;
         attempt++;
         continue;
       }
-      const content = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      try {
-        const decision = JSON.parse(content);
-        return {
-          targetAgent: decision.targetAgent,
-          reasoning: decision.reasoning,
-          confidence: decision.confidence,
-          strategy: "llm-based",
-          timestamp: Date.now()
-        };
-      } catch (error) {
-        throw new Error(`Failed to parse routing decision from LLM: ${error}`);
+      let decision;
+      if (response && typeof response === "object" && ("targetAgent" in response || "targetAgents" in response)) {
+        decision = response;
+      } else if (response.content) {
+        if (typeof response.content === "string") {
+          try {
+            decision = JSON.parse(response.content);
+          } catch (error) {
+            throw new Error(`Failed to parse routing decision from LLM. Expected JSON but got: ${response.content}`);
+          }
+        } else if (typeof response.content === "object") {
+          decision = response.content;
+        } else {
+          throw new Error(`Unexpected response content type: ${typeof response.content}`);
+        }
+      } else {
+        throw new Error(`Unexpected response format: ${JSON.stringify(response)}`);
       }
+      const result = {
+        targetAgent: decision.targetAgent,
+        targetAgents: decision.targetAgents,
+        reasoning: decision.reasoning,
+        confidence: decision.confidence,
+        strategy: "llm-based",
+        timestamp: Date.now()
+      };
+      return result;
     }
     throw new Error(`Max tool retries (${maxRetries}) exceeded without routing decision`);
   }
@@ -2011,6 +2051,7 @@ var roundRobinRouting = {
     const targetAgent = availableWorkers[lastRoutingIndex];
     return {
       targetAgent,
+      targetAgents: null,
       reasoning: `Round-robin selection: worker ${lastRoutingIndex + 1} of ${availableWorkers.length}`,
       confidence: 1,
       strategy: "round-robin",
@@ -2040,6 +2081,7 @@ var skillBasedRouting = {
       }
       return {
         targetAgent: firstAvailable[0],
+        targetAgents: null,
         reasoning: "No skill matches found, using first available worker",
         confidence: 0.5,
         strategy: "skill-based",
@@ -2050,6 +2092,7 @@ var skillBasedRouting = {
     const confidence = Math.min(best.score / 5, 1);
     return {
       targetAgent: best.id,
+      targetAgents: null,
       reasoning: `Best skill match with score ${best.score} (skills: ${best.skills.join(", ")})`,
       confidence,
       strategy: "skill-based",
@@ -2069,6 +2112,7 @@ var loadBalancedRouting = {
     const confidence = targetWorker.workload === 0 ? 1 : Math.max(0.5, 1 - targetWorker.workload / (avgWorkload * 2));
     return {
       targetAgent: targetWorker.id,
+      targetAgents: null,
       reasoning: `Lowest workload: ${targetWorker.workload} tasks (avg: ${avgWorkload.toFixed(1)})`,
       confidence,
       strategy: "load-balanced",
@@ -2124,10 +2168,7 @@ function wrapReActAgent(workerId, agent, verbose = false) {
       );
       if (!currentAssignment) {
         logger.debug("No active assignment found", { workerId });
-        return {
-          currentAgent: "supervisor",
-          status: "routing"
-        };
+        return {};
       }
       const result = await agent.invoke(
         {
@@ -2159,9 +2200,7 @@ function wrapReActAgent(workerId, agent, verbose = false) {
         }
       };
       return {
-        completedTasks: [taskResult],
-        currentAgent: "supervisor",
-        status: "routing"
+        completedTasks: [taskResult]
       };
     } catch (error) {
       if (error && typeof error === "object" && "constructor" in error && error.constructor.name === "GraphInterrupt") {
@@ -2232,7 +2271,7 @@ function createSupervisorNode(config) {
         };
       }
       const allCompleted = state.activeAssignments.every(
-        (assignment2) => state.completedTasks.some((task) => task.assignmentId === assignment2.id)
+        (assignment) => state.completedTasks.some((task2) => task2.assignmentId === assignment.id)
       );
       if (allCompleted && state.activeAssignments.length > 0) {
         if (verbose) {
@@ -2245,20 +2284,29 @@ function createSupervisorNode(config) {
       }
       const routingImpl = getRoutingStrategy(strategy);
       const decision = await routingImpl.route(state, config);
+      const targetAgents = decision.targetAgents && decision.targetAgents.length > 0 ? decision.targetAgents : decision.targetAgent ? [decision.targetAgent] : [];
+      if (targetAgents.length === 0) {
+        throw new Error("Routing decision must specify at least one target agent");
+      }
       if (verbose) {
-        console.log(`[Supervisor] Routing to ${decision.targetAgent}: ${decision.reasoning}`);
+        if (targetAgents.length === 1) {
+          console.log(`[Supervisor] Routing to ${targetAgents[0]}: ${decision.reasoning}`);
+        } else {
+          console.log(`[Supervisor] Routing to ${targetAgents.length} agents in parallel [${targetAgents.join(", ")}]: ${decision.reasoning}`);
+        }
       }
-      const assignment = {
+      const task = state.messages[state.messages.length - 1]?.content || state.input;
+      const assignments = targetAgents.map((workerId) => ({
         id: `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
-        workerId: decision.targetAgent,
-        task: state.messages[state.messages.length - 1]?.content || state.input,
+        workerId,
+        task,
         priority: 5,
         assignedAt: Date.now()
-      };
-      const message = {
+      }));
+      const messages = assignments.map((assignment) => ({
         id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
         from: "supervisor",
-        to: [decision.targetAgent],
+        to: [assignment.workerId],
         type: "task_assignment",
         content: assignment.task,
         timestamp: Date.now(),
@@ -2266,13 +2314,15 @@ function createSupervisorNode(config) {
           assignmentId: assignment.id,
           priority: assignment.priority
         }
-      };
+      }));
       return {
-        currentAgent: decision.targetAgent,
+        currentAgent: targetAgents.join(","),
+        // Store all agents (for backward compat)
         status: "executing",
         routingHistory: [decision],
-        activeAssignments: [assignment],
-        messages: [message],
+        activeAssignments: assignments,
+        // Multiple assignments for parallel execution!
+        messages,
         iteration: state.iteration + 1
       };
     } catch (error) {
@@ -2307,10 +2357,7 @@ function createWorkerNode(config) {
         if (verbose) {
           console.log(`[Worker:${id}] No active assignment found`);
         }
-        return {
-          currentAgent: "supervisor",
-          status: "routing"
-        };
+        return {};
       }
       if (executeFn) {
         if (verbose) {
@@ -2385,9 +2432,7 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
       return {
         completedTasks: [taskResult],
         messages: [message],
-        workers: updatedWorkers,
-        currentAgent: "supervisor",
-        status: "routing"
+        workers: updatedWorkers
       };
     } catch (error) {
       if (error && typeof error === "object" && "constructor" in error && error.constructor.name === "GraphInterrupt") {
@@ -2500,10 +2545,16 @@ function createMultiAgentSystem(config) {
   } = config;
   const workflow = new import_langgraph4.StateGraph(MultiAgentState);
   let supervisorConfig = { ...supervisor, maxIterations, verbose };
-  if (supervisor.model && supervisor.tools && supervisor.tools.length > 0) {
-    const langchainTools = (0, import_core9.toLangChainTools)(supervisor.tools);
-    const modelWithTools = supervisor.model.bindTools(langchainTools);
-    supervisorConfig.model = modelWithTools;
+  if (supervisor.model) {
+    let configuredModel = supervisor.model;
+    if (supervisor.strategy === "llm-based") {
+      configuredModel = configuredModel.withStructuredOutput(RoutingDecisionSchema);
+    }
+    if (supervisor.tools && supervisor.tools.length > 0) {
+      const langchainTools = (0, import_core9.toLangChainTools)(supervisor.tools);
+      configuredModel = configuredModel.bindTools(langchainTools);
+    }
+    supervisorConfig.model = configuredModel;
   }
   const supervisorNode = createSupervisorNode(supervisorConfig);
   workflow.addNode("supervisor", supervisorNode);
@@ -2531,6 +2582,10 @@ function createMultiAgentSystem(config) {
       return "aggregator";
     }
     if (state.currentAgent && state.currentAgent !== "supervisor") {
+      if (state.currentAgent.includes(",")) {
+        const agents = state.currentAgent.split(",").map((a) => a.trim());
+        return agents;
+      }
       return state.currentAgent;
     }
     return "supervisor";

package/dist/index.d.cts

@@ -1860,40 +1860,70 @@ declare const RoutingStrategySchema: z.ZodEnum<["llm-based", "rule-based", "roun
 type RoutingStrategy = z.infer<typeof RoutingStrategySchema>;
 /**
  * Schema for routing decision
+ *
+ * Supports both single-agent and parallel multi-agent routing:
+ * - Single: Use `targetAgent` field
+ * - Parallel: Use `targetAgents` array field
+ *
+ * If both are provided, `targetAgents` takes precedence.
+ *
+ * Note: Uses .nullable() instead of .optional() for OpenAI structured output compatibility
  */
-declare const RoutingDecisionSchema: z.ZodObject<{
+declare const RoutingDecisionSchema: z.ZodEffects<z.ZodObject<{
     /**
-     * Target agent to route to
+     * Target agent to route to (single agent routing)
+     * @deprecated Use targetAgents for parallel routing support
      */
-    targetAgent: z.ZodString;
+    targetAgent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /**
+     * Target agents to route to (parallel routing)
+     * When multiple agents are specified, they execute in parallel
+     */
+    targetAgents: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
     /**
      * Reasoning for the routing decision
      */
-    reasoning: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodDefault<z.ZodString>;
     /**
      * Confidence in the routing decision (0-1)
      */
-    confidence: z.ZodOptional<z.ZodNumber>;
+    confidence: z.ZodDefault<z.ZodNumber>;
     /**
      * Strategy used for routing
      */
-    strategy: z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>;
+    strategy: z.ZodDefault<z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>>;
     /**
      * Timestamp of the routing decision
      */
-    timestamp: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    targetAgent: string;
+    timestamp: number;
+    reasoning: string;
+    confidence: number;
+    targetAgent: string | null;
+    targetAgents: string[] | null;
     strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+}, {
     timestamp?: number | undefined;
     reasoning?: string | undefined;
     confidence?: number | undefined;
-}, {
-    targetAgent: string;
+    targetAgent?: string | null | undefined;
+    targetAgents?: string[] | null | undefined;
+    strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
+}>, {
+    timestamp: number;
+    reasoning: string;
+    confidence: number;
+    targetAgent: string | null;
+    targetAgents: string[] | null;
     strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+}, {
     timestamp?: number | undefined;
     reasoning?: string | undefined;
     confidence?: number | undefined;
+    targetAgent?: string | null | undefined;
+    targetAgents?: string[] | null | undefined;
+    strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
 }>;
 type RoutingDecision = z.infer<typeof RoutingDecisionSchema>;
 /**
@@ -2166,31 +2196,49 @@ declare const MultiAgentStateConfig: {
      * Accumulates all routing decisions
      */
     routingHistory: {
-        schema: z.ZodArray<z.ZodObject<{
-            targetAgent: z.ZodString;
-            reasoning: z.ZodOptional<z.ZodString>;
-            confidence: z.ZodOptional<z.ZodNumber>;
-            strategy: z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>;
-            timestamp: z.ZodOptional<z.ZodNumber>;
+        schema: z.ZodArray<z.ZodEffects<z.ZodObject<{
+            targetAgent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            targetAgents: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+            reasoning: z.ZodDefault<z.ZodString>;
+            confidence: z.ZodDefault<z.ZodNumber>;
+            strategy: z.ZodDefault<z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>>;
+            timestamp: z.ZodDefault<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
-            targetAgent: string;
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+        }, {
             timestamp?: number | undefined;
             reasoning?: string | undefined;
             confidence?: number | undefined;
-        }, {
-            targetAgent: string;
+            targetAgent?: string | null | undefined;
+            targetAgents?: string[] | null | undefined;
+            strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
+        }>, {
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+        }, {
             timestamp?: number | undefined;
             reasoning?: string | undefined;
             confidence?: number | undefined;
+            targetAgent?: string | null | undefined;
+            targetAgents?: string[] | null | undefined;
+            strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
         }>, "many">;
         reducer: (left: RoutingDecision[], right: RoutingDecision[]) => {
-            targetAgent: string;
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
-            timestamp?: number | undefined;
-            reasoning?: string | undefined;
-            confidence?: number | undefined;
         }[];
         default: () => never[];
         description: string;
@@ -2606,7 +2654,7 @@ interface RoutingStrategyImpl {
 /**
  * Default system prompt for LLM-based routing
  */
-declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent responsible for routing tasks to specialized worker agents.\n\nYour job is to:\n1. Analyze the current task and context\n2. Review available worker capabilities\n3. Select the most appropriate worker for the task\n4. Provide clear reasoning for your decision\n\nRespond with a JSON object containing:\n{\n  \"targetAgent\": \"worker_id\",\n  \"reasoning\": \"explanation of why this worker is best suited\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}";
+declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent responsible for routing tasks to specialized worker agents.\n\nYour job is to:\n1. Analyze the current task and context\n2. Review available worker capabilities\n3. Select the most appropriate worker(s) for the task\n4. Provide clear reasoning for your decision\n\n**IMPORTANT: You can route to MULTIPLE workers for parallel execution when:**\n- The task requires information from multiple domains (e.g., code + documentation)\n- Multiple workers have complementary expertise\n- Parallel execution would provide a more comprehensive answer\n\n**Response Format:**\n\nFor SINGLE worker routing:\n{\n  \"targetAgent\": \"worker_id\",\n  \"reasoning\": \"explanation of why this worker is best suited\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}\n\nFor PARALLEL multi-worker routing:\n{\n  \"targetAgents\": [\"worker_id_1\", \"worker_id_2\", ...],\n  \"reasoning\": \"explanation of why these workers should work in parallel\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}\n\nChoose parallel routing when the task benefits from multiple perspectives or data sources.";
 /**
  * LLM-based routing strategy
  * Uses an LLM to intelligently route tasks based on worker capabilities

package/dist/index.d.ts

@@ -1860,40 +1860,70 @@ declare const RoutingStrategySchema: z.ZodEnum<["llm-based", "rule-based", "roun
 type RoutingStrategy = z.infer<typeof RoutingStrategySchema>;
 /**
  * Schema for routing decision
+ *
+ * Supports both single-agent and parallel multi-agent routing:
+ * - Single: Use `targetAgent` field
+ * - Parallel: Use `targetAgents` array field
+ *
+ * If both are provided, `targetAgents` takes precedence.
+ *
+ * Note: Uses .nullable() instead of .optional() for OpenAI structured output compatibility
  */
-declare const RoutingDecisionSchema: z.ZodObject<{
+declare const RoutingDecisionSchema: z.ZodEffects<z.ZodObject<{
     /**
-     * Target agent to route to
+     * Target agent to route to (single agent routing)
+     * @deprecated Use targetAgents for parallel routing support
      */
-    targetAgent: z.ZodString;
+    targetAgent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /**
+     * Target agents to route to (parallel routing)
+     * When multiple agents are specified, they execute in parallel
+     */
+    targetAgents: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
     /**
      * Reasoning for the routing decision
      */
-    reasoning: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodDefault<z.ZodString>;
     /**
      * Confidence in the routing decision (0-1)
      */
-    confidence: z.ZodOptional<z.ZodNumber>;
+    confidence: z.ZodDefault<z.ZodNumber>;
     /**
      * Strategy used for routing
      */
-    strategy: z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>;
+    strategy: z.ZodDefault<z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>>;
     /**
      * Timestamp of the routing decision
      */
-    timestamp: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    targetAgent: string;
+    timestamp: number;
+    reasoning: string;
+    confidence: number;
+    targetAgent: string | null;
+    targetAgents: string[] | null;
     strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+}, {
     timestamp?: number | undefined;
     reasoning?: string | undefined;
     confidence?: number | undefined;
-}, {
-    targetAgent: string;
+    targetAgent?: string | null | undefined;
+    targetAgents?: string[] | null | undefined;
+    strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
+}>, {
+    timestamp: number;
+    reasoning: string;
+    confidence: number;
+    targetAgent: string | null;
+    targetAgents: string[] | null;
     strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+}, {
     timestamp?: number | undefined;
     reasoning?: string | undefined;
     confidence?: number | undefined;
+    targetAgent?: string | null | undefined;
+    targetAgents?: string[] | null | undefined;
+    strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
 }>;
 type RoutingDecision = z.infer<typeof RoutingDecisionSchema>;
 /**
@@ -2166,31 +2196,49 @@ declare const MultiAgentStateConfig: {
      * Accumulates all routing decisions
      */
     routingHistory: {
-        schema: z.ZodArray<z.ZodObject<{
-            targetAgent: z.ZodString;
-            reasoning: z.ZodOptional<z.ZodString>;
-            confidence: z.ZodOptional<z.ZodNumber>;
-            strategy: z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>;
-            timestamp: z.ZodOptional<z.ZodNumber>;
+        schema: z.ZodArray<z.ZodEffects<z.ZodObject<{
+            targetAgent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            targetAgents: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+            reasoning: z.ZodDefault<z.ZodString>;
+            confidence: z.ZodDefault<z.ZodNumber>;
+            strategy: z.ZodDefault<z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>>;
+            timestamp: z.ZodDefault<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
-            targetAgent: string;
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+        }, {
             timestamp?: number | undefined;
             reasoning?: string | undefined;
             confidence?: number | undefined;
-        }, {
-            targetAgent: string;
+            targetAgent?: string | null | undefined;
+            targetAgents?: string[] | null | undefined;
+            strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
+        }>, {
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+        }, {
             timestamp?: number | undefined;
             reasoning?: string | undefined;
             confidence?: number | undefined;
+            targetAgent?: string | null | undefined;
+            targetAgents?: string[] | null | undefined;
+            strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
         }>, "many">;
         reducer: (left: RoutingDecision[], right: RoutingDecision[]) => {
-            targetAgent: string;
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
-            timestamp?: number | undefined;
-            reasoning?: string | undefined;
-            confidence?: number | undefined;
         }[];
         default: () => never[];
         description: string;
@@ -2606,7 +2654,7 @@ interface RoutingStrategyImpl {
 /**
  * Default system prompt for LLM-based routing
  */
-declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent responsible for routing tasks to specialized worker agents.\n\nYour job is to:\n1. Analyze the current task and context\n2. Review available worker capabilities\n3. Select the most appropriate worker for the task\n4. Provide clear reasoning for your decision\n\nRespond with a JSON object containing:\n{\n  \"targetAgent\": \"worker_id\",\n  \"reasoning\": \"explanation of why this worker is best suited\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}";
+declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent responsible for routing tasks to specialized worker agents.\n\nYour job is to:\n1. Analyze the current task and context\n2. Review available worker capabilities\n3. Select the most appropriate worker(s) for the task\n4. Provide clear reasoning for your decision\n\n**IMPORTANT: You can route to MULTIPLE workers for parallel execution when:**\n- The task requires information from multiple domains (e.g., code + documentation)\n- Multiple workers have complementary expertise\n- Parallel execution would provide a more comprehensive answer\n\n**Response Format:**\n\nFor SINGLE worker routing:\n{\n  \"targetAgent\": \"worker_id\",\n  \"reasoning\": \"explanation of why this worker is best suited\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}\n\nFor PARALLEL multi-worker routing:\n{\n  \"targetAgents\": [\"worker_id_1\", \"worker_id_2\", ...],\n  \"reasoning\": \"explanation of why these workers should work in parallel\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}\n\nChoose parallel routing when the task benefits from multiple perspectives or data sources.";
 /**
  * LLM-based routing strategy
  * Uses an LLM to intelligently route tasks based on worker capabilities

package/dist/index.js

@@ -1543,26 +1543,35 @@ var RoutingStrategySchema = z7.enum([
 ]);
 var RoutingDecisionSchema = z7.object({
   /**
-   * Target agent to route to
+   * Target agent to route to (single agent routing)
+   * @deprecated Use targetAgents for parallel routing support
    */
-  targetAgent: z7.string().describe("Agent to route the task to"),
+  targetAgent: z7.string().nullable().default(null).describe("Agent to route the task to (single routing)"),
+  /**
+   * Target agents to route to (parallel routing)
+   * When multiple agents are specified, they execute in parallel
+   */
+  targetAgents: z7.array(z7.string()).nullable().default(null).describe("Agents to route the task to (parallel routing)"),
   /**
    * Reasoning for the routing decision
    */
-  reasoning: z7.string().optional().describe("Explanation for routing decision"),
+  reasoning: z7.string().default("").describe("Explanation for routing decision"),
   /**
    * Confidence in the routing decision (0-1)
    */
-  confidence: z7.number().min(0).max(1).optional().describe("Confidence score"),
+  confidence: z7.number().min(0).max(1).default(0.8).describe("Confidence score"),
   /**
    * Strategy used for routing
    */
-  strategy: RoutingStrategySchema.describe("Strategy used for this decision"),
+  strategy: RoutingStrategySchema.default("llm-based").describe("Strategy used for this decision"),
   /**
    * Timestamp of the routing decision
    */
-  timestamp: z7.number().optional().describe("Timestamp of the decision")
-});
+  timestamp: z7.number().default(() => Date.now()).describe("Timestamp of the decision")
+}).refine(
+  (data) => data.targetAgent || data.targetAgents && data.targetAgents.length > 0,
+  { message: "Either targetAgent or targetAgents must be provided" }
+);
 var WorkerCapabilitiesSchema = z7.object({
   /**
    * Skills/capabilities the agent has
@@ -1830,16 +1839,33 @@ var DEFAULT_SUPERVISOR_SYSTEM_PROMPT = `You are a supervisor agent responsible f
 Your job is to:
 1. Analyze the current task and context
 2. Review available worker capabilities
-3. Select the most appropriate worker for the task
+3. Select the most appropriate worker(s) for the task
 4. Provide clear reasoning for your decision
 
-Respond with a JSON object containing:
+**IMPORTANT: You can route to MULTIPLE workers for parallel execution when:**
+- The task requires information from multiple domains (e.g., code + documentation)
+- Multiple workers have complementary expertise
+- Parallel execution would provide a more comprehensive answer
+
+**Response Format:**
+
+For SINGLE worker routing:
 {
   "targetAgent": "worker_id",
   "reasoning": "explanation of why this worker is best suited",
   "confidence": 0.0-1.0,
   "strategy": "llm-based"
-}`;
+}
+
+For PARALLEL multi-worker routing:
+{
+  "targetAgents": ["worker_id_1", "worker_id_2", ...],
+  "reasoning": "explanation of why these workers should work in parallel",
+  "confidence": 0.0-1.0,
+  "strategy": "llm-based"
+}
+
+Choose parallel routing when the task benefits from multiple perspectives or data sources.`;
 var llmBasedRouting = {
   name: "llm-based",
   async route(state, config) {
@@ -1862,7 +1888,7 @@ var llmBasedRouting = {
 Available workers:
 ${workerInfo}
 
-Select the best worker for this task and explain your reasoning.`;
+Select the best worker(s) for this task and explain your reasoning.`;
     const conversationHistory = [];
     let attempt = 0;
     while (attempt < maxRetries) {
@@ -1884,19 +1910,33 @@ Select the best worker for this task and explain your reasoning.`;
         attempt++;
         continue;
       }
-      const content = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      try {
-        const decision = JSON.parse(content);
-        return {
-          targetAgent: decision.targetAgent,
-          reasoning: decision.reasoning,
-          confidence: decision.confidence,
-          strategy: "llm-based",
-          timestamp: Date.now()
-        };
-      } catch (error) {
-        throw new Error(`Failed to parse routing decision from LLM: ${error}`);
+      let decision;
+      if (response && typeof response === "object" && ("targetAgent" in response || "targetAgents" in response)) {
+        decision = response;
+      } else if (response.content) {
+        if (typeof response.content === "string") {
+          try {
+            decision = JSON.parse(response.content);
+          } catch (error) {
+            throw new Error(`Failed to parse routing decision from LLM. Expected JSON but got: ${response.content}`);
+          }
+        } else if (typeof response.content === "object") {
+          decision = response.content;
+        } else {
+          throw new Error(`Unexpected response content type: ${typeof response.content}`);
+        }
+      } else {
+        throw new Error(`Unexpected response format: ${JSON.stringify(response)}`);
       }
+      const result = {
+        targetAgent: decision.targetAgent,
+        targetAgents: decision.targetAgents,
+        reasoning: decision.reasoning,
+        confidence: decision.confidence,
+        strategy: "llm-based",
+        timestamp: Date.now()
+      };
+      return result;
     }
     throw new Error(`Max tool retries (${maxRetries}) exceeded without routing decision`);
   }
@@ -1912,6 +1952,7 @@ var roundRobinRouting = {
     const targetAgent = availableWorkers[lastRoutingIndex];
     return {
       targetAgent,
+      targetAgents: null,
       reasoning: `Round-robin selection: worker ${lastRoutingIndex + 1} of ${availableWorkers.length}`,
       confidence: 1,
       strategy: "round-robin",
@@ -1941,6 +1982,7 @@ var skillBasedRouting = {
       }
       return {
         targetAgent: firstAvailable[0],
+        targetAgents: null,
         reasoning: "No skill matches found, using first available worker",
         confidence: 0.5,
         strategy: "skill-based",
@@ -1951,6 +1993,7 @@ var skillBasedRouting = {
     const confidence = Math.min(best.score / 5, 1);
     return {
       targetAgent: best.id,
+      targetAgents: null,
       reasoning: `Best skill match with score ${best.score} (skills: ${best.skills.join(", ")})`,
       confidence,
       strategy: "skill-based",
@@ -1970,6 +2013,7 @@ var loadBalancedRouting = {
     const confidence = targetWorker.workload === 0 ? 1 : Math.max(0.5, 1 - targetWorker.workload / (avgWorkload * 2));
     return {
       targetAgent: targetWorker.id,
+      targetAgents: null,
       reasoning: `Lowest workload: ${targetWorker.workload} tasks (avg: ${avgWorkload.toFixed(1)})`,
       confidence,
       strategy: "load-balanced",
@@ -2025,10 +2069,7 @@ function wrapReActAgent(workerId, agent, verbose = false) {
       );
       if (!currentAssignment) {
         logger.debug("No active assignment found", { workerId });
-        return {
-          currentAgent: "supervisor",
-          status: "routing"
-        };
+        return {};
       }
       const result = await agent.invoke(
         {
@@ -2060,9 +2101,7 @@ function wrapReActAgent(workerId, agent, verbose = false) {
         }
       };
       return {
-        completedTasks: [taskResult],
-        currentAgent: "supervisor",
-        status: "routing"
+        completedTasks: [taskResult]
       };
     } catch (error) {
       if (error && typeof error === "object" && "constructor" in error && error.constructor.name === "GraphInterrupt") {
@@ -2133,7 +2172,7 @@ function createSupervisorNode(config) {
         };
       }
       const allCompleted = state.activeAssignments.every(
-        (assignment2) => state.completedTasks.some((task) => task.assignmentId === assignment2.id)
+        (assignment) => state.completedTasks.some((task2) => task2.assignmentId === assignment.id)
       );
       if (allCompleted && state.activeAssignments.length > 0) {
         if (verbose) {
@@ -2146,20 +2185,29 @@ function createSupervisorNode(config) {
       }
       const routingImpl = getRoutingStrategy(strategy);
       const decision = await routingImpl.route(state, config);
+      const targetAgents = decision.targetAgents && decision.targetAgents.length > 0 ? decision.targetAgents : decision.targetAgent ? [decision.targetAgent] : [];
+      if (targetAgents.length === 0) {
+        throw new Error("Routing decision must specify at least one target agent");
+      }
       if (verbose) {
-        console.log(`[Supervisor] Routing to ${decision.targetAgent}: ${decision.reasoning}`);
+        if (targetAgents.length === 1) {
+          console.log(`[Supervisor] Routing to ${targetAgents[0]}: ${decision.reasoning}`);
+        } else {
+          console.log(`[Supervisor] Routing to ${targetAgents.length} agents in parallel [${targetAgents.join(", ")}]: ${decision.reasoning}`);
+        }
       }
-      const assignment = {
+      const task = state.messages[state.messages.length - 1]?.content || state.input;
+      const assignments = targetAgents.map((workerId) => ({
         id: `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
-        workerId: decision.targetAgent,
-        task: state.messages[state.messages.length - 1]?.content || state.input,
+        workerId,
+        task,
         priority: 5,
         assignedAt: Date.now()
-      };
-      const message = {
+      }));
+      const messages = assignments.map((assignment) => ({
         id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
         from: "supervisor",
-        to: [decision.targetAgent],
+        to: [assignment.workerId],
         type: "task_assignment",
         content: assignment.task,
         timestamp: Date.now(),
@@ -2167,13 +2215,15 @@ function createSupervisorNode(config) {
           assignmentId: assignment.id,
           priority: assignment.priority
         }
-      };
+      }));
       return {
-        currentAgent: decision.targetAgent,
+        currentAgent: targetAgents.join(","),
+        // Store all agents (for backward compat)
         status: "executing",
         routingHistory: [decision],
-        activeAssignments: [assignment],
-        messages: [message],
+        activeAssignments: assignments,
+        // Multiple assignments for parallel execution!
+        messages,
         iteration: state.iteration + 1
       };
     } catch (error) {
@@ -2208,10 +2258,7 @@ function createWorkerNode(config) {
         if (verbose) {
           console.log(`[Worker:${id}] No active assignment found`);
         }
-        return {
-          currentAgent: "supervisor",
-          status: "routing"
-        };
+        return {};
       }
       if (executeFn) {
         if (verbose) {
@@ -2286,9 +2333,7 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
       return {
         completedTasks: [taskResult],
         messages: [message],
-        workers: updatedWorkers,
-        currentAgent: "supervisor",
-        status: "routing"
+        workers: updatedWorkers
       };
     } catch (error) {
       if (error && typeof error === "object" && "constructor" in error && error.constructor.name === "GraphInterrupt") {
@@ -2401,10 +2446,16 @@ function createMultiAgentSystem(config) {
   } = config;
   const workflow = new StateGraph4(MultiAgentState);
   let supervisorConfig = { ...supervisor, maxIterations, verbose };
-  if (supervisor.model && supervisor.tools && supervisor.tools.length > 0) {
-    const langchainTools = toLangChainTools3(supervisor.tools);
-    const modelWithTools = supervisor.model.bindTools(langchainTools);
-    supervisorConfig.model = modelWithTools;
+  if (supervisor.model) {
+    let configuredModel = supervisor.model;
+    if (supervisor.strategy === "llm-based") {
+      configuredModel = configuredModel.withStructuredOutput(RoutingDecisionSchema);
+    }
+    if (supervisor.tools && supervisor.tools.length > 0) {
+      const langchainTools = toLangChainTools3(supervisor.tools);
+      configuredModel = configuredModel.bindTools(langchainTools);
+    }
+    supervisorConfig.model = configuredModel;
   }
   const supervisorNode = createSupervisorNode(supervisorConfig);
   workflow.addNode("supervisor", supervisorNode);
@@ -2432,6 +2483,10 @@ function createMultiAgentSystem(config) {
       return "aggregator";
     }
     if (state.currentAgent && state.currentAgent !== "supervisor") {
+      if (state.currentAgent.includes(",")) {
+        const agents = state.currentAgent.split(",").map((a) => a.trim());
+        return agents;
+      }
       return state.currentAgent;
     }
     return "supervisor";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/patterns",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Agent patterns (ReAct, Planner-Executor) for AgentForge framework",
   "type": "module",
   "main": "./dist/index.cjs",