@agentforge/patterns 0.7.0 → 0.8.1

package/dist/index.d.cts

@@ -172,7 +172,12 @@ interface ReActAgentConfig {
      * Optional checkpointer for state persistence
      * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
      *
+     * Can be:
+     * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+     * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+     *
      * @example
+     * Standalone agent with its own checkpointer:
      * ```typescript
      * import { MemorySaver } from '@langchain/langgraph';
      *
@@ -183,8 +188,18 @@ interface ReActAgentConfig {
      *   checkpointer
      * });
      * ```
+     *
+     * @example
+     * Nested agent using parent's checkpointer (for multi-agent systems):
+     * ```typescript
+     * const agent = createReActAgent({
+     *   model,
+     *   tools,
+     *   checkpointer: true  // Use parent's checkpointer with separate namespace
+     * });
+     * ```
      */
-    checkpointer?: BaseCheckpointSaver;
+    checkpointer?: BaseCheckpointSaver | true;
     /**
      * Enable tool call deduplication to prevent calling the same tool with identical parameters multiple times
      * @default true
@@ -287,6 +302,31 @@ declare const DEFAULT_REACT_SYSTEM_PROMPT = "You are a helpful assistant that us
  *   { configurable: { thread_id: 'conversation-123' } }
  * );
  * ```
+ *
+ * @example
+ * As a nested agent in a multi-agent system:
+ * ```typescript
+ * import { createReActAgent, createMultiAgentSystem } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * // Create worker agent with checkpointer: true to use parent's checkpointer
+ * const hrAgent = createReActAgent({
+ *   model: new ChatOpenAI({ model: 'gpt-4' }),
+ *   tools: [createAskHumanTool(), ...hrTools],
+ *   checkpointer: true  // Use parent's checkpointer with separate namespace
+ * });
+ *
+ * // Create multi-agent system with its own checkpointer
+ * const system = createMultiAgentSystem({
+ *   workers: { hr: hrAgent },
+ *   checkpointer: new MemorySaver()  // Parent checkpointer
+ * });
+ *
+ * // When hrAgent calls askHuman, it will use a separate checkpoint namespace
+ * // Format: {parent_thread_id}:worker:hr
+ * ```
  */
 declare function createReActAgent(config: ReActAgentConfig, options?: ReActBuilderOptions): CompiledStateGraph<any, any>;
 
@@ -372,6 +412,40 @@ declare class ReActAgentBuilder {
         action?: string;
         observation?: string;
     }): this;
+    /**
+     * Set the checkpointer for state persistence (optional)
+     *
+     * Can be:
+     * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+     * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+     *
+     * Required for human-in-the-loop workflows (askHuman tool) and conversation continuity.
+     *
+     * @param checkpointer - Checkpointer instance or `true` for nested graphs
+     *
+     * @example
+     * Standalone agent with its own checkpointer:
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const agent = new ReActAgentBuilder()
+     *   .withModel(model)
+     *   .withTools(tools)
+     *   .withCheckpointer(new MemorySaver())
+     *   .build();
+     * ```
+     *
+     * @example
+     * Nested agent using parent's checkpointer (for multi-agent systems):
+     * ```typescript
+     * const agent = new ReActAgentBuilder()
+     *   .withModel(model)
+     *   .withTools(tools)
+     *   .withCheckpointer(true)  // Use parent's checkpointer with separate namespace
+     *   .build();
+     * ```
+     */
+    withCheckpointer(checkpointer: any): this;
     /**
      * Build the ReAct agent
      *
@@ -2473,29 +2547,6 @@ 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
      *
@@ -2616,7 +2667,20 @@ interface MultiAgentSystemConfig {
      * Optional checkpointer for state persistence
      * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
      *
+     * **Worker Checkpoint Namespaces:**
+     * When worker agents are configured with `checkpointer: true`, they automatically use
+     * separate checkpoint namespaces to enable proper handling of nested graph interrupts.
+     *
+     * The namespace format is: `{parent_thread_id}:worker:{workerId}`
+     *
+     * For example, if the parent thread ID is `thread_abc123` and the worker ID is `hr`,
+     * the worker's checkpoint namespace will be `thread_abc123:worker:hr`.
+     *
+     * This allows worker agents to use the `askHuman` tool without causing infinite loops,
+     * as each worker's state is saved and resumed independently.
+     *
      * @example
+     * Basic usage with checkpointer:
      * ```typescript
      * import { MemorySaver } from '@langchain/langgraph';
      *
@@ -2627,6 +2691,35 @@ interface MultiAgentSystemConfig {
      *   checkpointer
      * });
      * ```
+     *
+     * @example
+     * Worker agents with nested graph interrupts:
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     * import { createReActAgent } from '@agentforge/patterns';
+     * import { createAskHumanTool } from '@agentforge/tools';
+     *
+     * // Create worker agent with checkpointer: true
+     * const hrAgent = createReActAgent({
+     *   model,
+     *   tools: [createAskHumanTool(), ...hrTools],
+     *   checkpointer: true  // Use parent's checkpointer with separate namespace
+     * });
+     *
+     * // Create multi-agent system with checkpointer
+     * const system = createMultiAgentSystem({
+     *   supervisor: { strategy: 'skill-based', model },
+     *   workers: [{
+     *     id: 'hr',
+     *     capabilities: { skills: ['hr'], ... },
+     *     agent: hrAgent
+     *   }],
+     *   checkpointer: new MemorySaver()
+     * });
+     *
+     * // When hrAgent calls askHuman, it will use checkpoint namespace:
+     * // thread_abc123:worker:hr
+     * ```
      */
     checkpointer?: BaseCheckpointSaver;
 }
@@ -2672,8 +2765,6 @@ 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;
 /**

package/dist/index.d.ts

@@ -172,7 +172,12 @@ interface ReActAgentConfig {
      * Optional checkpointer for state persistence
      * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
      *
+     * Can be:
+     * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+     * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+     *
      * @example
+     * Standalone agent with its own checkpointer:
      * ```typescript
      * import { MemorySaver } from '@langchain/langgraph';
      *
@@ -183,8 +188,18 @@ interface ReActAgentConfig {
      *   checkpointer
      * });
      * ```
+     *
+     * @example
+     * Nested agent using parent's checkpointer (for multi-agent systems):
+     * ```typescript
+     * const agent = createReActAgent({
+     *   model,
+     *   tools,
+     *   checkpointer: true  // Use parent's checkpointer with separate namespace
+     * });
+     * ```
      */
-    checkpointer?: BaseCheckpointSaver;
+    checkpointer?: BaseCheckpointSaver | true;
     /**
      * Enable tool call deduplication to prevent calling the same tool with identical parameters multiple times
      * @default true
@@ -287,6 +302,31 @@ declare const DEFAULT_REACT_SYSTEM_PROMPT = "You are a helpful assistant that us
  *   { configurable: { thread_id: 'conversation-123' } }
  * );
  * ```
+ *
+ * @example
+ * As a nested agent in a multi-agent system:
+ * ```typescript
+ * import { createReActAgent, createMultiAgentSystem } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * // Create worker agent with checkpointer: true to use parent's checkpointer
+ * const hrAgent = createReActAgent({
+ *   model: new ChatOpenAI({ model: 'gpt-4' }),
+ *   tools: [createAskHumanTool(), ...hrTools],
+ *   checkpointer: true  // Use parent's checkpointer with separate namespace
+ * });
+ *
+ * // Create multi-agent system with its own checkpointer
+ * const system = createMultiAgentSystem({
+ *   workers: { hr: hrAgent },
+ *   checkpointer: new MemorySaver()  // Parent checkpointer
+ * });
+ *
+ * // When hrAgent calls askHuman, it will use a separate checkpoint namespace
+ * // Format: {parent_thread_id}:worker:hr
+ * ```
  */
 declare function createReActAgent(config: ReActAgentConfig, options?: ReActBuilderOptions): CompiledStateGraph<any, any>;
 
@@ -372,6 +412,40 @@ declare class ReActAgentBuilder {
         action?: string;
         observation?: string;
     }): this;
+    /**
+     * Set the checkpointer for state persistence (optional)
+     *
+     * Can be:
+     * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+     * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+     *
+     * Required for human-in-the-loop workflows (askHuman tool) and conversation continuity.
+     *
+     * @param checkpointer - Checkpointer instance or `true` for nested graphs
+     *
+     * @example
+     * Standalone agent with its own checkpointer:
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const agent = new ReActAgentBuilder()
+     *   .withModel(model)
+     *   .withTools(tools)
+     *   .withCheckpointer(new MemorySaver())
+     *   .build();
+     * ```
+     *
+     * @example
+     * Nested agent using parent's checkpointer (for multi-agent systems):
+     * ```typescript
+     * const agent = new ReActAgentBuilder()
+     *   .withModel(model)
+     *   .withTools(tools)
+     *   .withCheckpointer(true)  // Use parent's checkpointer with separate namespace
+     *   .build();
+     * ```
+     */
+    withCheckpointer(checkpointer: any): this;
     /**
      * Build the ReAct agent
      *
@@ -2473,29 +2547,6 @@ 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
      *
@@ -2616,7 +2667,20 @@ interface MultiAgentSystemConfig {
      * Optional checkpointer for state persistence
      * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
      *
+     * **Worker Checkpoint Namespaces:**
+     * When worker agents are configured with `checkpointer: true`, they automatically use
+     * separate checkpoint namespaces to enable proper handling of nested graph interrupts.
+     *
+     * The namespace format is: `{parent_thread_id}:worker:{workerId}`
+     *
+     * For example, if the parent thread ID is `thread_abc123` and the worker ID is `hr`,
+     * the worker's checkpoint namespace will be `thread_abc123:worker:hr`.
+     *
+     * This allows worker agents to use the `askHuman` tool without causing infinite loops,
+     * as each worker's state is saved and resumed independently.
+     *
      * @example
+     * Basic usage with checkpointer:
      * ```typescript
      * import { MemorySaver } from '@langchain/langgraph';
      *
@@ -2627,6 +2691,35 @@ interface MultiAgentSystemConfig {
      *   checkpointer
      * });
      * ```
+     *
+     * @example
+     * Worker agents with nested graph interrupts:
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     * import { createReActAgent } from '@agentforge/patterns';
+     * import { createAskHumanTool } from '@agentforge/tools';
+     *
+     * // Create worker agent with checkpointer: true
+     * const hrAgent = createReActAgent({
+     *   model,
+     *   tools: [createAskHumanTool(), ...hrTools],
+     *   checkpointer: true  // Use parent's checkpointer with separate namespace
+     * });
+     *
+     * // Create multi-agent system with checkpointer
+     * const system = createMultiAgentSystem({
+     *   supervisor: { strategy: 'skill-based', model },
+     *   workers: [{
+     *     id: 'hr',
+     *     capabilities: { skills: ['hr'], ... },
+     *     agent: hrAgent
+     *   }],
+     *   checkpointer: new MemorySaver()
+     * });
+     *
+     * // When hrAgent calls askHuman, it will use checkpoint namespace:
+     * // thread_abc123:worker:hr
+     * ```
      */
     checkpointer?: BaseCheckpointSaver;
 }
@@ -2672,8 +2765,6 @@ 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;
 /**