@agentforge/patterns 0.5.3 → 0.6.0

package/dist/index.cjs

@@ -394,7 +394,8 @@ function createReActAgent(config, options) {
     systemPrompt = DEFAULT_REACT_SYSTEM_PROMPT,
     maxIterations = 10,
     returnIntermediateSteps = false,
-    stopCondition
+    stopCondition,
+    checkpointer
   } = config;
   const {
     verbose = false,
@@ -429,7 +430,7 @@ function createReActAgent(config, options) {
     return ACTION_NODE;
   };
   const workflow = new import_langgraph.StateGraph(ReActState).addNode(REASONING_NODE, reasoningNode).addNode(ACTION_NODE, actionNode).addNode(OBSERVATION_NODE, observationNode).addEdge("__start__", REASONING_NODE).addConditionalEdges(REASONING_NODE, shouldContinue).addEdge(ACTION_NODE, OBSERVATION_NODE).addEdge(OBSERVATION_NODE, REASONING_NODE);
-  return workflow.compile();
+  return workflow.compile(checkpointer ? { checkpointer } : void 0);
 }
 
 // src/react/builder.ts
@@ -970,7 +971,8 @@ function createPlanExecuteAgent(config) {
     executor,
     replanner,
     maxIterations = 5,
-    verbose = false
+    verbose = false,
+    checkpointer
   } = config;
   const plannerNode = createPlannerNode(planner);
   const executorNode = createExecutorNode(executor);
@@ -1030,7 +1032,7 @@ function createPlanExecuteAgent(config) {
       finish: import_langgraph2.END
     }
   );
-  return workflow.compile();
+  return workflow.compile(checkpointer ? { checkpointer } : void 0);
 }
 
 // src/reflection/state.ts
@@ -1507,7 +1509,8 @@ function createReflectionAgent(config) {
     reviser,
     maxIterations = 3,
     qualityCriteria,
-    verbose = false
+    verbose = false,
+    checkpointer
   } = config;
   const generatorNode = createGeneratorNode({ ...generator, verbose });
   const reflectorNode = createReflectorNode({ ...reflector, qualityCriteria, verbose });
@@ -1565,7 +1568,7 @@ function createReflectionAgent(config) {
       error: import_langgraph3.END
     }
   ).addEdge("finisher", import_langgraph3.END);
-  return workflow.compile();
+  return workflow.compile(checkpointer ? { checkpointer } : void 0);
 }
 
 // src/multi-agent/state.ts
@@ -1888,6 +1891,33 @@ var MultiAgentState = (0, import_core6.createStateAnnotation)(MultiAgentStateCon
 
 // src/multi-agent/routing.ts
 var import_messages4 = require("@langchain/core/messages");
+async function executeTools(toolCalls, tools) {
+  const results = [];
+  for (const toolCall of toolCalls) {
+    const tool = tools.find((t) => t.metadata.name === toolCall.name);
+    if (!tool) {
+      results.push(new import_messages4.ToolMessage({
+        content: `Error: Tool '${toolCall.name}' not found`,
+        tool_call_id: toolCall.id
+      }));
+      continue;
+    }
+    try {
+      const result = await tool.execute(toolCall.args);
+      const content = typeof result === "string" ? result : JSON.stringify(result);
+      results.push(new import_messages4.ToolMessage({
+        content,
+        tool_call_id: toolCall.id
+      }));
+    } catch (error) {
+      results.push(new import_messages4.ToolMessage({
+        content: `Error executing tool: ${error.message}`,
+        tool_call_id: toolCall.id
+      }));
+    }
+  }
+  return results;
+}
 var DEFAULT_SUPERVISOR_SYSTEM_PROMPT = `You are a supervisor agent responsible for routing tasks to specialized worker agents.
 
 Your job is to:
@@ -1910,11 +1940,13 @@ var llmBasedRouting = {
       throw new Error("LLM-based routing requires a model to be configured");
     }
     const systemPrompt = config.systemPrompt || DEFAULT_SUPERVISOR_SYSTEM_PROMPT;
+    const maxRetries = config.maxToolRetries || 3;
+    const tools = config.tools || [];
     const workerInfo = Object.entries(state.workers).map(([id, caps]) => {
       const skills = caps.skills.join(", ");
-      const tools = caps.tools.join(", ");
+      const tools2 = caps.tools.join(", ");
       const available = caps.available ? "available" : "busy";
-      return `- ${id}: Skills: [${skills}], Tools: [${tools}], Status: ${available}, Workload: ${caps.currentWorkload}`;
+      return `- ${id}: Skills: [${skills}], Tools: [${tools2}], Status: ${available}, Workload: ${caps.currentWorkload}`;
     }).join("\n");
     const lastMessage = state.messages[state.messages.length - 1];
     const taskContext = lastMessage?.content || state.input;
@@ -1924,24 +1956,42 @@ Available workers:
 ${workerInfo}
 
 Select the best worker for this task and explain your reasoning.`;
-    const messages = [
-      new import_messages4.SystemMessage(systemPrompt),
-      new import_messages4.HumanMessage(userPrompt)
-    ];
-    const response = await config.model.invoke(messages);
-    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}`);
+    const conversationHistory = [];
+    let attempt = 0;
+    while (attempt < maxRetries) {
+      const messages = [
+        new import_messages4.SystemMessage(systemPrompt),
+        new import_messages4.HumanMessage(userPrompt),
+        ...conversationHistory
+      ];
+      const response = await config.model.invoke(messages);
+      if (response.tool_calls && response.tool_calls.length > 0) {
+        if (tools.length === 0) {
+          throw new Error("LLM requested tool calls but no tools are configured");
+        }
+        const toolResults = await executeTools(response.tool_calls, tools);
+        conversationHistory.push(
+          new import_messages4.AIMessage({ content: response.content || "", tool_calls: response.tool_calls }),
+          ...toolResults
+        );
+        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}`);
+      }
     }
+    throw new Error(`Max tool retries (${maxRetries}) exceeded without routing decision`);
   }
 };
 var roundRobinRouting = {
@@ -2416,20 +2466,24 @@ Please synthesize these results into a comprehensive response that addresses the
 
 // src/multi-agent/agent.ts
 var import_langgraph4 = require("@langchain/langgraph");
+var import_core8 = require("@agentforge/core");
 function createMultiAgentSystem(config) {
   const {
     supervisor,
     workers,
     aggregator,
     maxIterations = 10,
-    verbose = false
+    verbose = false,
+    checkpointer
   } = config;
   const workflow = new import_langgraph4.StateGraph(MultiAgentState);
-  const supervisorNode = createSupervisorNode({
-    ...supervisor,
-    maxIterations,
-    verbose
-  });
+  let supervisorConfig = { ...supervisor, maxIterations, verbose };
+  if (supervisor.model && supervisor.tools && supervisor.tools.length > 0) {
+    const langchainTools = (0, import_core8.toLangChainTools)(supervisor.tools);
+    const modelWithTools = supervisor.model.bindTools(langchainTools);
+    supervisorConfig.model = modelWithTools;
+  }
+  const supervisorNode = createSupervisorNode(supervisorConfig);
   workflow.addNode("supervisor", supervisorNode);
   const workerIds = [];
   const workerCapabilities = {};
@@ -2475,7 +2529,7 @@ function createMultiAgentSystem(config) {
     workflow.addConditionalEdges(workerId, workerRouter, ["supervisor"]);
   }
   workflow.addConditionalEdges("aggregator", aggregatorRouter, [import_langgraph4.END]);
-  const compiled = workflow.compile();
+  const compiled = workflow.compile(checkpointer ? { checkpointer } : void 0);
   const originalInvoke = compiled.invoke.bind(compiled);
   compiled.invoke = async function(input, config2) {
     const mergedInput = {

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import * as _langchain_langgraph from '@langchain/langgraph';
-import { CompiledStateGraph } from '@langchain/langgraph';
+import { BaseCheckpointSaver, CompiledStateGraph } from '@langchain/langgraph';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import { ToolRegistry, Tool } from '@agentforge/core';
 
@@ -164,6 +164,23 @@ interface ReActAgentConfig {
      * Return true to stop the ReAct loop
      */
     stopCondition?: (state: ReActStateType) => boolean;
+    /**
+     * Optional checkpointer for state persistence
+     * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
+     *
+     * @example
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const checkpointer = new MemorySaver();
+     * const agent = createReActAgent({
+     *   model,
+     *   tools,
+     *   checkpointer
+     * });
+     * ```
+     */
+    checkpointer?: BaseCheckpointSaver;
 }
 /**
  * Options for the ReAct agent builder
@@ -221,6 +238,7 @@ declare const DEFAULT_REACT_SYSTEM_PROMPT = "You are a helpful assistant that us
  * @returns A compiled LangGraph StateGraph
  *
  * @example
+ * Basic usage:
  * ```typescript
  * import { createReActAgent } from '@agentforge/patterns';
  * import { ChatOpenAI } from '@langchain/openai';
@@ -236,6 +254,30 @@ declare const DEFAULT_REACT_SYSTEM_PROMPT = "You are a helpful assistant that us
  *   messages: [{ role: 'user', content: 'What is the weather?' }]
  * });
  * ```
+ *
+ * @example
+ * With checkpointer for human-in-the-loop workflows:
+ * ```typescript
+ * import { createReActAgent } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const checkpointer = new MemorySaver();
+ * const askHuman = createAskHumanTool();
+ *
+ * const agent = createReActAgent({
+ *   model: new ChatOpenAI({ model: 'gpt-4' }),
+ *   tools: [askHuman, ...otherTools],
+ *   checkpointer  // Required for askHuman tool
+ * });
+ *
+ * // Invoke with thread_id for conversation continuity
+ * const result = await agent.invoke(
+ *   { messages: [{ role: 'user', content: 'Help me with this task' }] },
+ *   { configurable: { thread_id: 'conversation-123' } }
+ * );
+ * ```
  */
 declare function createReActAgent(config: ReActAgentConfig, options?: ReActBuilderOptions): CompiledStateGraph<any, any>;
 
@@ -887,6 +929,23 @@ interface PlanExecuteAgentConfig {
      * Verbose logging
      */
     verbose?: boolean;
+    /**
+     * Optional checkpointer for state persistence
+     * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
+     *
+     * @example
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const checkpointer = new MemorySaver();
+     * const agent = createPlanExecuteAgent({
+     *   planner: { model },
+     *   executor: { tools },
+     *   checkpointer
+     * });
+     * ```
+     */
+    checkpointer?: BaseCheckpointSaver;
 }
 /**
  * Node function type for Plan-Execute pattern
@@ -919,6 +978,7 @@ type PlanExecuteRouter = (state: PlanExecuteStateType) => PlanExecuteRoute;
  * @returns A compiled LangGraph StateGraph
  *
  * @example
+ * Basic usage:
  * ```typescript
  * import { createPlanExecuteAgent } from '@agentforge/patterns';
  * import { ChatOpenAI } from '@langchain/openai';
@@ -942,6 +1002,30 @@ type PlanExecuteRouter = (state: PlanExecuteStateType) => PlanExecuteRoute;
  *   input: 'Research the latest AI developments and summarize them'
  * });
  * ```
+ *
+ * @example
+ * With checkpointer for human-in-the-loop workflows:
+ * ```typescript
+ * import { createPlanExecuteAgent } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const checkpointer = new MemorySaver();
+ * const askHuman = createAskHumanTool();
+ *
+ * const agent = createPlanExecuteAgent({
+ *   planner: { model: new ChatOpenAI({ model: 'gpt-4' }), maxSteps: 5 },
+ *   executor: { tools: [askHuman, ...otherTools] },
+ *   checkpointer  // Required for askHuman tool
+ * });
+ *
+ * // Invoke with thread_id for conversation continuity
+ * const result = await agent.invoke(
+ *   { input: 'Help me plan this project' },
+ *   { configurable: { thread_id: 'conversation-123' } }
+ * );
+ * ```
  */
 declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): any;
 
@@ -1525,6 +1609,24 @@ interface ReflectionAgentConfig {
      * Whether to include verbose logging
      */
     verbose?: boolean;
+    /**
+     * Optional checkpointer for state persistence
+     * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
+     *
+     * @example
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const checkpointer = new MemorySaver();
+     * const agent = createReflectionAgent({
+     *   generator: { model },
+     *   reflector: { model },
+     *   reviser: { model },
+     *   checkpointer
+     * });
+     * ```
+     */
+    checkpointer?: BaseCheckpointSaver;
 }
 /**
  * Node function type for reflection pattern
@@ -1630,6 +1732,7 @@ declare function createFinisherNode(): (state: ReflectionStateType) => Promise<P
  * @returns A compiled LangGraph StateGraph
  *
  * @example
+ * Basic usage:
  * ```typescript
  * import { createReflectionAgent } from '@agentforge/patterns';
  * import { ChatOpenAI } from '@langchain/openai';
@@ -1651,6 +1754,32 @@ declare function createFinisherNode(): (state: ReflectionStateType) => Promise<P
  *   input: 'Write an essay about AI safety'
  * });
  * ```
+ *
+ * @example
+ * With checkpointer for human-in-the-loop workflows:
+ * ```typescript
+ * import { createReflectionAgent } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const checkpointer = new MemorySaver();
+ * const model = new ChatOpenAI({ model: 'gpt-4' });
+ *
+ * const agent = createReflectionAgent({
+ *   generator: { model },
+ *   reflector: { model },
+ *   reviser: { model },
+ *   maxIterations: 3,
+ *   checkpointer  // Required for askHuman tool
+ * });
+ *
+ * // Invoke with thread_id for conversation continuity
+ * const result = await agent.invoke(
+ *   { input: 'Write a report on this topic' },
+ *   { configurable: { thread_id: 'conversation-123' } }
+ * );
+ * ```
  */
 declare function createReflectionAgent(config: ReflectionAgentConfig): any;
 
@@ -2282,6 +2411,37 @@ interface SupervisorConfig {
      * Maximum number of routing iterations
      */
     maxIterations?: number;
+    /**
+     * Optional tools the supervisor can use during routing
+     *
+     * Enables the supervisor to gather additional information before making routing decisions.
+     * Common use case: askHuman tool for clarifying ambiguous queries.
+     *
+     * Note: Only works with LLM-based routing strategy.
+     *
+     * @example
+     * ```typescript
+     * import { createAskHumanTool } from '@agentforge/tools';
+     *
+     * const system = createMultiAgentSystem({
+     *   supervisor: {
+     *     strategy: 'llm-based',
+     *     model: chatModel,
+     *     tools: [createAskHumanTool()],
+     *   },
+     *   // ...
+     * });
+     * ```
+     */
+    tools?: Tool<any, any>[];
+    /**
+     * Maximum number of tool call retries before requiring routing decision
+     *
+     * Prevents infinite loops where the supervisor keeps calling tools without making a routing decision.
+     *
+     * @default 3
+     */
+    maxToolRetries?: number;
 }
 /**
  * Configuration for a worker agent node
@@ -2387,6 +2547,23 @@ interface MultiAgentSystemConfig {
      * Whether to include verbose logging
      */
     verbose?: boolean;
+    /**
+     * Optional checkpointer for state persistence
+     * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
+     *
+     * @example
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const checkpointer = new MemorySaver();
+     * const system = createMultiAgentSystem({
+     *   supervisor: { strategy: 'skill-based', model },
+     *   workers: [...],
+     *   checkpointer
+     * });
+     * ```
+     */
+    checkpointer?: BaseCheckpointSaver;
 }
 /**
  * Node type for multi-agent graph
@@ -2430,6 +2607,8 @@ declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent res
 /**
  * LLM-based routing strategy
  * Uses an LLM to intelligently route tasks based on worker capabilities
+ *
+ * Supports tool calls (e.g., askHuman) for gathering additional information before routing.
  */
 declare const llmBasedRouting: RoutingStrategyImpl;
 /**
@@ -2494,6 +2673,7 @@ declare function createAggregatorNode(config?: AggregatorConfig): (state: MultiA
  * @returns Compiled LangGraph workflow
  *
  * @example
+ * Basic usage:
  * ```typescript
  * const system = createMultiAgentSystem({
  *   supervisor: {
@@ -2531,6 +2711,39 @@ declare function createAggregatorNode(config?: AggregatorConfig): (state: MultiA
  *   input: 'Research AI trends and write a summary',
  * });
  * ```
+ *
+ * @example
+ * With checkpointer for human-in-the-loop workflows:
+ * ```typescript
+ * import { createMultiAgentSystem } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const checkpointer = new MemorySaver();
+ * const askHuman = createAskHumanTool();
+ * const model = new ChatOpenAI({ model: 'gpt-4' });
+ *
+ * const system = createMultiAgentSystem({
+ *   supervisor: { strategy: 'skill-based', model },
+ *   workers: [
+ *     {
+ *       id: 'hr',
+ *       capabilities: { skills: ['hr'], tools: ['askHuman'], available: true, currentWorkload: 0 },
+ *       tools: [askHuman],
+ *       model,
+ *     },
+ *   ],
+ *   aggregator: { model },
+ *   checkpointer  // Required for askHuman tool
+ * });
+ *
+ * // Invoke with thread_id for conversation continuity
+ * const result = await system.invoke(
+ *   { input: 'Help me with HR policy question' },
+ *   { configurable: { thread_id: 'conversation-123' } }
+ * );
+ * ```
  */
 declare function createMultiAgentSystem(config: MultiAgentSystemConfig): CompiledStateGraph<{
     [x: string]: unknown;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import * as _langchain_langgraph from '@langchain/langgraph';
-import { CompiledStateGraph } from '@langchain/langgraph';
+import { BaseCheckpointSaver, CompiledStateGraph } from '@langchain/langgraph';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import { ToolRegistry, Tool } from '@agentforge/core';
 
@@ -164,6 +164,23 @@ interface ReActAgentConfig {
      * Return true to stop the ReAct loop
      */
     stopCondition?: (state: ReActStateType) => boolean;
+    /**
+     * Optional checkpointer for state persistence
+     * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
+     *
+     * @example
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const checkpointer = new MemorySaver();
+     * const agent = createReActAgent({
+     *   model,
+     *   tools,
+     *   checkpointer
+     * });
+     * ```
+     */
+    checkpointer?: BaseCheckpointSaver;
 }
 /**
  * Options for the ReAct agent builder
@@ -221,6 +238,7 @@ declare const DEFAULT_REACT_SYSTEM_PROMPT = "You are a helpful assistant that us
  * @returns A compiled LangGraph StateGraph
  *
  * @example
+ * Basic usage:
  * ```typescript
  * import { createReActAgent } from '@agentforge/patterns';
  * import { ChatOpenAI } from '@langchain/openai';
@@ -236,6 +254,30 @@ declare const DEFAULT_REACT_SYSTEM_PROMPT = "You are a helpful assistant that us
  *   messages: [{ role: 'user', content: 'What is the weather?' }]
  * });
  * ```
+ *
+ * @example
+ * With checkpointer for human-in-the-loop workflows:
+ * ```typescript
+ * import { createReActAgent } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const checkpointer = new MemorySaver();
+ * const askHuman = createAskHumanTool();
+ *
+ * const agent = createReActAgent({
+ *   model: new ChatOpenAI({ model: 'gpt-4' }),
+ *   tools: [askHuman, ...otherTools],
+ *   checkpointer  // Required for askHuman tool
+ * });
+ *
+ * // Invoke with thread_id for conversation continuity
+ * const result = await agent.invoke(
+ *   { messages: [{ role: 'user', content: 'Help me with this task' }] },
+ *   { configurable: { thread_id: 'conversation-123' } }
+ * );
+ * ```
  */
 declare function createReActAgent(config: ReActAgentConfig, options?: ReActBuilderOptions): CompiledStateGraph<any, any>;
 
@@ -887,6 +929,23 @@ interface PlanExecuteAgentConfig {
      * Verbose logging
      */
     verbose?: boolean;
+    /**
+     * Optional checkpointer for state persistence
+     * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
+     *
+     * @example
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const checkpointer = new MemorySaver();
+     * const agent = createPlanExecuteAgent({
+     *   planner: { model },
+     *   executor: { tools },
+     *   checkpointer
+     * });
+     * ```
+     */
+    checkpointer?: BaseCheckpointSaver;
 }
 /**
  * Node function type for Plan-Execute pattern
@@ -919,6 +978,7 @@ type PlanExecuteRouter = (state: PlanExecuteStateType) => PlanExecuteRoute;
  * @returns A compiled LangGraph StateGraph
  *
  * @example
+ * Basic usage:
  * ```typescript
  * import { createPlanExecuteAgent } from '@agentforge/patterns';
  * import { ChatOpenAI } from '@langchain/openai';
@@ -942,6 +1002,30 @@ type PlanExecuteRouter = (state: PlanExecuteStateType) => PlanExecuteRoute;
  *   input: 'Research the latest AI developments and summarize them'
  * });
  * ```
+ *
+ * @example
+ * With checkpointer for human-in-the-loop workflows:
+ * ```typescript
+ * import { createPlanExecuteAgent } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const checkpointer = new MemorySaver();
+ * const askHuman = createAskHumanTool();
+ *
+ * const agent = createPlanExecuteAgent({
+ *   planner: { model: new ChatOpenAI({ model: 'gpt-4' }), maxSteps: 5 },
+ *   executor: { tools: [askHuman, ...otherTools] },
+ *   checkpointer  // Required for askHuman tool
+ * });
+ *
+ * // Invoke with thread_id for conversation continuity
+ * const result = await agent.invoke(
+ *   { input: 'Help me plan this project' },
+ *   { configurable: { thread_id: 'conversation-123' } }
+ * );
+ * ```
  */
 declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): any;
 
@@ -1525,6 +1609,24 @@ interface ReflectionAgentConfig {
      * Whether to include verbose logging
      */
     verbose?: boolean;
+    /**
+     * Optional checkpointer for state persistence
+     * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
+     *
+     * @example
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const checkpointer = new MemorySaver();
+     * const agent = createReflectionAgent({
+     *   generator: { model },
+     *   reflector: { model },
+     *   reviser: { model },
+     *   checkpointer
+     * });
+     * ```
+     */
+    checkpointer?: BaseCheckpointSaver;
 }
 /**
  * Node function type for reflection pattern
@@ -1630,6 +1732,7 @@ declare function createFinisherNode(): (state: ReflectionStateType) => Promise<P
  * @returns A compiled LangGraph StateGraph
  *
  * @example
+ * Basic usage:
  * ```typescript
  * import { createReflectionAgent } from '@agentforge/patterns';
  * import { ChatOpenAI } from '@langchain/openai';
@@ -1651,6 +1754,32 @@ declare function createFinisherNode(): (state: ReflectionStateType) => Promise<P
  *   input: 'Write an essay about AI safety'
  * });
  * ```
+ *
+ * @example
+ * With checkpointer for human-in-the-loop workflows:
+ * ```typescript
+ * import { createReflectionAgent } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const checkpointer = new MemorySaver();
+ * const model = new ChatOpenAI({ model: 'gpt-4' });
+ *
+ * const agent = createReflectionAgent({
+ *   generator: { model },
+ *   reflector: { model },
+ *   reviser: { model },
+ *   maxIterations: 3,
+ *   checkpointer  // Required for askHuman tool
+ * });
+ *
+ * // Invoke with thread_id for conversation continuity
+ * const result = await agent.invoke(
+ *   { input: 'Write a report on this topic' },
+ *   { configurable: { thread_id: 'conversation-123' } }
+ * );
+ * ```
  */
 declare function createReflectionAgent(config: ReflectionAgentConfig): any;
 
@@ -2282,6 +2411,37 @@ interface SupervisorConfig {
      * Maximum number of routing iterations
      */
     maxIterations?: number;
+    /**
+     * Optional tools the supervisor can use during routing
+     *
+     * Enables the supervisor to gather additional information before making routing decisions.
+     * Common use case: askHuman tool for clarifying ambiguous queries.
+     *
+     * Note: Only works with LLM-based routing strategy.
+     *
+     * @example
+     * ```typescript
+     * import { createAskHumanTool } from '@agentforge/tools';
+     *
+     * const system = createMultiAgentSystem({
+     *   supervisor: {
+     *     strategy: 'llm-based',
+     *     model: chatModel,
+     *     tools: [createAskHumanTool()],
+     *   },
+     *   // ...
+     * });
+     * ```
+     */
+    tools?: Tool<any, any>[];
+    /**
+     * Maximum number of tool call retries before requiring routing decision
+     *
+     * Prevents infinite loops where the supervisor keeps calling tools without making a routing decision.
+     *
+     * @default 3
+     */
+    maxToolRetries?: number;
 }
 /**
  * Configuration for a worker agent node
@@ -2387,6 +2547,23 @@ interface MultiAgentSystemConfig {
      * Whether to include verbose logging
      */
     verbose?: boolean;
+    /**
+     * Optional checkpointer for state persistence
+     * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
+     *
+     * @example
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const checkpointer = new MemorySaver();
+     * const system = createMultiAgentSystem({
+     *   supervisor: { strategy: 'skill-based', model },
+     *   workers: [...],
+     *   checkpointer
+     * });
+     * ```
+     */
+    checkpointer?: BaseCheckpointSaver;
 }
 /**
  * Node type for multi-agent graph
@@ -2430,6 +2607,8 @@ declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent res
 /**
  * LLM-based routing strategy
  * Uses an LLM to intelligently route tasks based on worker capabilities
+ *
+ * Supports tool calls (e.g., askHuman) for gathering additional information before routing.
  */
 declare const llmBasedRouting: RoutingStrategyImpl;
 /**
@@ -2494,6 +2673,7 @@ declare function createAggregatorNode(config?: AggregatorConfig): (state: MultiA
  * @returns Compiled LangGraph workflow
  *
  * @example
+ * Basic usage:
  * ```typescript
  * const system = createMultiAgentSystem({
  *   supervisor: {
@@ -2531,6 +2711,39 @@ declare function createAggregatorNode(config?: AggregatorConfig): (state: MultiA
  *   input: 'Research AI trends and write a summary',
  * });
  * ```
+ *
+ * @example
+ * With checkpointer for human-in-the-loop workflows:
+ * ```typescript
+ * import { createMultiAgentSystem } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const checkpointer = new MemorySaver();
+ * const askHuman = createAskHumanTool();
+ * const model = new ChatOpenAI({ model: 'gpt-4' });
+ *
+ * const system = createMultiAgentSystem({
+ *   supervisor: { strategy: 'skill-based', model },
+ *   workers: [
+ *     {
+ *       id: 'hr',
+ *       capabilities: { skills: ['hr'], tools: ['askHuman'], available: true, currentWorkload: 0 },
+ *       tools: [askHuman],
+ *       model,
+ *     },
+ *   ],
+ *   aggregator: { model },
+ *   checkpointer  // Required for askHuman tool
+ * });
+ *
+ * // Invoke with thread_id for conversation continuity
+ * const result = await system.invoke(
+ *   { input: 'Help me with HR policy question' },
+ *   { configurable: { thread_id: 'conversation-123' } }
+ * );
+ * ```
  */
 declare function createMultiAgentSystem(config: MultiAgentSystemConfig): CompiledStateGraph<{
     [x: string]: unknown;

package/dist/index.js

@@ -295,7 +295,8 @@ function createReActAgent(config, options) {
     systemPrompt = DEFAULT_REACT_SYSTEM_PROMPT,
     maxIterations = 10,
     returnIntermediateSteps = false,
-    stopCondition
+    stopCondition,
+    checkpointer
   } = config;
   const {
     verbose = false,
@@ -330,7 +331,7 @@ function createReActAgent(config, options) {
     return ACTION_NODE;
   };
   const workflow = new StateGraph(ReActState).addNode(REASONING_NODE, reasoningNode).addNode(ACTION_NODE, actionNode).addNode(OBSERVATION_NODE, observationNode).addEdge("__start__", REASONING_NODE).addConditionalEdges(REASONING_NODE, shouldContinue).addEdge(ACTION_NODE, OBSERVATION_NODE).addEdge(OBSERVATION_NODE, REASONING_NODE);
-  return workflow.compile();
+  return workflow.compile(checkpointer ? { checkpointer } : void 0);
 }
 
 // src/react/builder.ts
@@ -871,7 +872,8 @@ function createPlanExecuteAgent(config) {
     executor,
     replanner,
     maxIterations = 5,
-    verbose = false
+    verbose = false,
+    checkpointer
   } = config;
   const plannerNode = createPlannerNode(planner);
   const executorNode = createExecutorNode(executor);
@@ -931,7 +933,7 @@ function createPlanExecuteAgent(config) {
       finish: END2
     }
   );
-  return workflow.compile();
+  return workflow.compile(checkpointer ? { checkpointer } : void 0);
 }
 
 // src/reflection/state.ts
@@ -1408,7 +1410,8 @@ function createReflectionAgent(config) {
     reviser,
     maxIterations = 3,
     qualityCriteria,
-    verbose = false
+    verbose = false,
+    checkpointer
   } = config;
   const generatorNode = createGeneratorNode({ ...generator, verbose });
   const reflectorNode = createReflectorNode({ ...reflector, qualityCriteria, verbose });
@@ -1466,7 +1469,7 @@ function createReflectionAgent(config) {
       error: END3
     }
   ).addEdge("finisher", END3);
-  return workflow.compile();
+  return workflow.compile(checkpointer ? { checkpointer } : void 0);
 }
 
 // src/multi-agent/state.ts
@@ -1788,7 +1791,34 @@ var MultiAgentStateConfig = {
 var MultiAgentState = createStateAnnotation4(MultiAgentStateConfig);
 
 // src/multi-agent/routing.ts
-import { HumanMessage as HumanMessage4, SystemMessage as SystemMessage4 } from "@langchain/core/messages";
+import { HumanMessage as HumanMessage4, SystemMessage as SystemMessage4, AIMessage as AIMessage2, ToolMessage as ToolMessage2 } from "@langchain/core/messages";
+async function executeTools(toolCalls, tools) {
+  const results = [];
+  for (const toolCall of toolCalls) {
+    const tool = tools.find((t) => t.metadata.name === toolCall.name);
+    if (!tool) {
+      results.push(new ToolMessage2({
+        content: `Error: Tool '${toolCall.name}' not found`,
+        tool_call_id: toolCall.id
+      }));
+      continue;
+    }
+    try {
+      const result = await tool.execute(toolCall.args);
+      const content = typeof result === "string" ? result : JSON.stringify(result);
+      results.push(new ToolMessage2({
+        content,
+        tool_call_id: toolCall.id
+      }));
+    } catch (error) {
+      results.push(new ToolMessage2({
+        content: `Error executing tool: ${error.message}`,
+        tool_call_id: toolCall.id
+      }));
+    }
+  }
+  return results;
+}
 var DEFAULT_SUPERVISOR_SYSTEM_PROMPT = `You are a supervisor agent responsible for routing tasks to specialized worker agents.
 
 Your job is to:
@@ -1811,11 +1841,13 @@ var llmBasedRouting = {
       throw new Error("LLM-based routing requires a model to be configured");
     }
     const systemPrompt = config.systemPrompt || DEFAULT_SUPERVISOR_SYSTEM_PROMPT;
+    const maxRetries = config.maxToolRetries || 3;
+    const tools = config.tools || [];
     const workerInfo = Object.entries(state.workers).map(([id, caps]) => {
       const skills = caps.skills.join(", ");
-      const tools = caps.tools.join(", ");
+      const tools2 = caps.tools.join(", ");
       const available = caps.available ? "available" : "busy";
-      return `- ${id}: Skills: [${skills}], Tools: [${tools}], Status: ${available}, Workload: ${caps.currentWorkload}`;
+      return `- ${id}: Skills: [${skills}], Tools: [${tools2}], Status: ${available}, Workload: ${caps.currentWorkload}`;
     }).join("\n");
     const lastMessage = state.messages[state.messages.length - 1];
     const taskContext = lastMessage?.content || state.input;
@@ -1825,24 +1857,42 @@ Available workers:
 ${workerInfo}
 
 Select the best worker for this task and explain your reasoning.`;
-    const messages = [
-      new SystemMessage4(systemPrompt),
-      new HumanMessage4(userPrompt)
-    ];
-    const response = await config.model.invoke(messages);
-    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}`);
+    const conversationHistory = [];
+    let attempt = 0;
+    while (attempt < maxRetries) {
+      const messages = [
+        new SystemMessage4(systemPrompt),
+        new HumanMessage4(userPrompt),
+        ...conversationHistory
+      ];
+      const response = await config.model.invoke(messages);
+      if (response.tool_calls && response.tool_calls.length > 0) {
+        if (tools.length === 0) {
+          throw new Error("LLM requested tool calls but no tools are configured");
+        }
+        const toolResults = await executeTools(response.tool_calls, tools);
+        conversationHistory.push(
+          new AIMessage2({ content: response.content || "", tool_calls: response.tool_calls }),
+          ...toolResults
+        );
+        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}`);
+      }
     }
+    throw new Error(`Max tool retries (${maxRetries}) exceeded without routing decision`);
   }
 };
 var roundRobinRouting = {
@@ -2317,20 +2367,24 @@ Please synthesize these results into a comprehensive response that addresses the
 
 // src/multi-agent/agent.ts
 import { StateGraph as StateGraph4, END as END4 } from "@langchain/langgraph";
+import { toLangChainTools as toLangChainTools3 } from "@agentforge/core";
 function createMultiAgentSystem(config) {
   const {
     supervisor,
     workers,
     aggregator,
     maxIterations = 10,
-    verbose = false
+    verbose = false,
+    checkpointer
   } = config;
   const workflow = new StateGraph4(MultiAgentState);
-  const supervisorNode = createSupervisorNode({
-    ...supervisor,
-    maxIterations,
-    verbose
-  });
+  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;
+  }
+  const supervisorNode = createSupervisorNode(supervisorConfig);
   workflow.addNode("supervisor", supervisorNode);
   const workerIds = [];
   const workerCapabilities = {};
@@ -2376,7 +2430,7 @@ function createMultiAgentSystem(config) {
     workflow.addConditionalEdges(workerId, workerRouter, ["supervisor"]);
   }
   workflow.addConditionalEdges("aggregator", aggregatorRouter, [END4]);
-  const compiled = workflow.compile();
+  const compiled = workflow.compile(checkpointer ? { checkpointer } : void 0);
   const originalInvoke = compiled.invoke.bind(compiled);
   compiled.invoke = async function(input, config2) {
     const mergedInput = {

package/package.json

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