@agentforge/patterns

@agentforge/patterns

Production-ready agent patterns for the AgentForge framework

🎉 Status: Production Ready & Published

All 4 patterns complete | 143 tests passing | Full TypeScript support | Comprehensive documentation

🤖 Agent Patterns

✅ ReAct Pattern (Reasoning and Action)

The ReAct pattern implements a thought-action-observation loop for exploratory tasks:

• Think - Reason about what to do next
• Act - Execute a tool or provide final answer
• Observe - Process the result
• Repeat - Continue until task complete

Best for: Research, exploration, problem-solving, multi-step reasoning

Features:

• Type-safe state with Zod schemas
• Fluent builder API (ReActAgentBuilder)
• Configurable max iterations and timeouts
• Comprehensive error handling
• 55 tests - Full coverage

✅ Plan-Execute Pattern

The Plan-Execute pattern separates planning from execution for complex, structured tasks:

• Plan - Create a multi-step plan
• Execute - Execute each step (sequential or parallel)
• Replan (optional) - Adjust based on results
• Finish - Synthesize final response

Best for: Complex workflows, data analysis, structured problem-solving

Features:

• Structured multi-step planning
• Sequential & parallel execution
• Dependency management
• Adaptive replanning
• Progress tracking
• 35+ tests - Comprehensive coverage

✅ Reflection Pattern

The Reflection pattern implements iterative self-improvement through critique and revision:

• Generate - Create initial response
• Reflect - Critique the output
• Revise - Improve based on critique
• Repeat - Continue until quality threshold met

Best for: Content generation, code review, quality optimization

Features:

• Iterative improvement cycles
• Self-critique capabilities
• Quality-focused optimization
• Flexible reflection criteria
• Configurable iteration limits
• 30+ tests - Full coverage

✅ Multi-Agent Pattern

The Multi-Agent pattern coordinates multiple specialized agents for complex tasks:

• Supervisor - Routes tasks to workers
• Workers - Execute specialized tasks
• Aggregator - Combines results
• Routing - Intelligent task distribution

Best for: Customer support, complex workflows, specialized task distribution

Features:

• Specialized worker agents
• Flexible routing strategies (LLM-based, skill-based, rule-based, round-robin, load-balanced)
• Parallel execution support
• Intelligent result aggregation
• Dynamic worker registration
• 22+ tests - Comprehensive coverage

Installation

pnpm add @agentforge/patterns @agentforge/core

Quick Start

ReAct Agent

Simple reasoning and action loop:

import { ReActAgentBuilder } from '@agentforge/patterns';
import { toolBuilder, ToolCategory } from '@agentforge/core';
import { ChatOpenAI } from '@langchain/openai';
import { z } from 'zod';

// Create a tool
const calculatorTool = toolBuilder()
  .name('calculator')
  .description('Perform arithmetic operations')
  .category(ToolCategory.UTILITY)
  .schema(
    z.object({
      operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
      a: z.number(),
      b: z.number(),
    })
  )
  .implement(async ({ operation, a, b }) => {
    switch (operation) {
      case 'add': return a + b;
      case 'subtract': return a - b;
      case 'multiply': return a * b;
      case 'divide': return a / b;
    }
  })
  .build();

// Create the agent
const agent = new ReActAgentBuilder()
  .withLLM(new ChatOpenAI({ model: 'gpt-4' }))
  .withTools([calculatorTool])
  .withMaxIterations(10)
  .build();

// Use the agent
const result = await agent.invoke({
  messages: [{ role: 'user', content: 'What is 15 * 7?' }],
});

console.log(result.response); // "The result is 105"

Plan-Execute Agent

Structured planning and execution:

import { createPlanExecuteAgent } from '@agentforge/patterns';
import { ChatOpenAI } from '@langchain/openai';
import { z } from 'zod';

// Create tools
const searchTool = {
  name: 'search',
  description: 'Search for information',
  schema: z.object({ query: z.string() }),
  metadata: { category: 'search' },
  invoke: async ({ query }) => {
    // Search implementation
    return { results: [...] };
  },
};

const analyzeTool = {
  name: 'analyze',
  description: 'Analyze data',
  schema: z.object({ data: z.any() }),
  metadata: { category: 'utility' },
  invoke: async ({ data }) => {
    // Analysis implementation
    return { insights: [...] };
  },
};

// Create the agent
const agent = createPlanExecuteAgent({
  planner: {
    model: new ChatOpenAI({ model: 'gpt-4' }),
    maxSteps: 5,
  },
  executor: {
    tools: [searchTool, analyzeTool],
    parallel: true, // Enable parallel execution
  },
  replanner: {
    model: new ChatOpenAI({ model: 'gpt-4' }),
    replanThreshold: 0.7, // Replan if confidence < 0.7
  },
});

// Use the agent
const result = await agent.invoke({
  input: 'Research AI developments and analyze trends',
});

console.log(result.plan); // The generated plan
console.log(result.pastSteps); // Executed steps
console.log(result.response); // Final synthesized response

Reflection Agent

Iterative self-improvement:

import { createReflectionAgent } from '@agentforge/patterns';
import { ChatOpenAI } from '@langchain/openai';

// Create the agent
const agent = createReflectionAgent({
  generator: {
    model: new ChatOpenAI({ model: 'gpt-4' }),
    systemPrompt: 'You are a professional writer. Create high-quality content.',
  },
  reflector: {
    model: new ChatOpenAI({ model: 'gpt-4' }),
    systemPrompt: 'Critique the content for clarity, engagement, and professionalism.',
  },
  reviser: {
    model: new ChatOpenAI({ model: 'gpt-4' }),
    systemPrompt: 'Revise the content based on the critique.',
  },
  maxIterations: 3,
  verbose: true,
});

// Use the agent
const result = await agent.invoke({
  input: 'Write a blog post about AI',
});

console.log(result.reflections); // All critiques
console.log(result.response); // Final refined response

Multi-Agent System

Coordinate specialized agents:

import { MultiAgentSystemBuilder } from '@agentforge/patterns';
import { ChatOpenAI } from '@langchain/openai';

const model = new ChatOpenAI({ model: 'gpt-4' });

// Create builder
const builder = new MultiAgentSystemBuilder({
  supervisor: {
    model,
    strategy: 'skill-based', // or 'llm-based', 'round-robin', etc.
  },
  aggregator: { model },
});

// Register specialized workers
builder.registerWorkers([
  {
    name: 'tech_support',
    description: 'Handles technical issues',
    capabilities: ['technical', 'troubleshooting', 'debugging'],
    model,
    tools: [diagnosticTool, troubleshootTool],
  },
  {
    name: 'billing_support',
    description: 'Handles billing inquiries',
    capabilities: ['billing', 'payments', 'refunds'],
    model,
    tools: [checkAccountTool, processRefundTool],
  },
]);

// Build and use the system
const system = builder.build();

const result = await system.invoke({
  input: 'My app keeps crashing and I need a refund',
});

console.log(result.response); // Aggregated response

Documentation

📖 Pattern Guides (GitHub Pages)

• 🤖 ReAct Pattern Guide - Comprehensive ReAct usage guide
• 📋 Plan-Execute Pattern Guide - Comprehensive Plan-Execute guide
• 🔄 Reflection Pattern Guide - Comprehensive Reflection guide
• 👥 Multi-Agent Pattern Guide - Comprehensive Multi-Agent guide

💡 Examples (GitHub Pages)

• ReAct Examples - ReAct pattern examples
• Plan-Execute Examples - Plan-Execute pattern examples
• Reflection Examples - Reflection pattern examples
• Multi-Agent Examples - Multi-Agent pattern examples

📂 Source Documentation

For contributors and advanced users, detailed implementation docs are available in the repository:

• Pattern Comparison - Detailed pattern comparison
• ReAct Implementation - ReAct implementation details
• Plan-Execute Implementation - Plan-Execute implementation details
• Reflection Implementation - Reflection implementation details
• Multi-Agent Implementation - Multi-Agent implementation details

API Reference

ReAct Pattern

import {
  ReActAgentBuilder,
  createReActAgent,
  createReActAgentBuilder,
} from '@agentforge/patterns';

Builder API:

• withLLM(llm) - Set the language model (required)
• withTools(tools) - Set tools array or registry (required)
• withSystemPrompt(prompt) - Set system prompt (optional)
• withMaxIterations(max) - Set max iterations (optional, default: 10)
• withReturnIntermediateSteps(value) - Include reasoning steps (optional)
• withStopCondition(fn) - Custom termination logic (optional)
• withVerbose(value) - Enable verbose logging (optional)
• withNodeNames(names) - Customize node names (optional)
• build() - Build the agent

Plan-Execute Pattern

import {
  createPlanExecuteAgent,
  createPlannerNode,
  createExecutorNode,
  createReplannerNode,
  createFinisherNode,
} from '@agentforge/patterns';

Main API:

• createPlanExecuteAgent(config) - Create a complete Plan-Execute agent

Configuration:

{
  planner: {
    model: BaseChatModel,          // LLM for planning
    systemPrompt?: string,         // Custom planning prompt
    maxSteps?: number,             // Max steps in plan (default: 7)
    includeToolDescriptions?: boolean,
  },
  executor: {
    tools: Tool[],                 // Available tools
    model?: BaseChatModel,         // Optional LLM for sub-tasks
    parallel?: boolean,            // Enable parallel execution
    stepTimeout?: number,          // Timeout per step (ms)
  },
  replanner?: {
    model: BaseChatModel,          // LLM for replanning
    replanThreshold?: number,      // Confidence threshold (0-1)
    systemPrompt?: string,         // Custom replanning prompt
  },
  maxIterations?: number,          // Max planning iterations
  verbose?: boolean,
}

Node Creators (for custom workflows):

• createPlannerNode(config) - Create planner node
• createExecutorNode(config) - Create executor node
• createReplannerNode(config) - Create replanner node
• createFinisherNode() - Create finisher node

Reflection Pattern

import {
  createReflectionAgent,
  createGeneratorNode,
  createReflectorNode,
  createReviserNode,
} from '@agentforge/patterns';

Main API:

• createReflectionAgent(config) - Create a complete Reflection agent

Configuration:

{
  generator: {
    model: BaseChatModel,          // LLM for generation
    systemPrompt?: string,         // Custom generation prompt
  },
  reflector: {
    model: BaseChatModel,          // LLM for reflection
    systemPrompt?: string,         // Custom reflection prompt
  },
  reviser: {
    model: BaseChatModel,          // LLM for revision
    systemPrompt?: string,         // Custom revision prompt
  },
  maxIterations?: number,          // Max reflection cycles (default: 3)
  qualityCriteria?: string[],      // Quality criteria for reflection
  verbose?: boolean,
}

Node Creators (for custom workflows):

• createGeneratorNode(config) - Create generator node
• createReflectorNode(config) - Create reflector node
• createReviserNode(config) - Create reviser node

Multi-Agent Pattern

import {
  createMultiAgentSystem,
  registerWorkers,
  createSupervisorNode,
  createWorkerNode,
  createAggregatorNode,
} from '@agentforge/patterns';

Main API:

• createMultiAgentSystem(config) - Create a complete Multi-Agent system
• MultiAgentSystemBuilder - Builder for creating Multi-Agent systems with workers
• registerWorkers(system, workers) - Update worker capabilities in state (Note: does not add worker nodes to compiled graphs; use builder or pass workers to createMultiAgentSystem)

Configuration:

{
  supervisor: {
    model: BaseChatModel,          // LLM for routing decisions
    strategy: RoutingStrategy,     // Routing strategy
    systemPrompt?: string,         // Custom supervisor prompt
  },
  workers: WorkerConfig[],        // Worker configurations
  aggregator: {
    model: BaseChatModel,          // LLM for aggregation
    systemPrompt?: string,         // Custom aggregator prompt
  },
  maxIterations?: number,          // Max coordination iterations
  verbose?: boolean,
}

Routing Strategies:

• 'llm-based' - LLM analyzes task and selects worker
• 'skill-based' - Match task to worker capabilities
• 'round-robin' - Distribute tasks evenly
• 'load-balanced' - Route to least busy worker
• Custom rule-based routing

Worker Configuration (for createMultiAgentSystem):

{
  id: string,                     // Unique worker identifier
  capabilities: {                 // Worker capabilities
    skills: string[],             // Worker skills
    tools: string[],              // Tool names (not objects)
    available: boolean,           // Availability status
    currentWorkload?: number,     // Current workload
  },
  tools?: Tool[],                 // Actual tool implementations
  model?: BaseChatModel,          // Worker-specific model
  systemPrompt?: string,          // Worker-specific prompt
  executeFn?: Function,           // Custom execution function
  agent?: CompiledStateGraph,     // Pre-built agent
}

Worker Configuration (for MultiAgentSystemBuilder.registerWorkers):

{
  name: string,                   // Worker name (becomes 'id')
  description?: string,           // Worker description
  capabilities: string[],         // Array of skill names
  tools?: Tool[],                 // Available tools
  model?: BaseChatModel,          // Worker-specific model
  systemPrompt?: string,          // Worker-specific prompt
}

Node Creators (for custom workflows):

• createSupervisorNode(config) - Create supervisor node
• createWorkerNode(config) - Create worker node
• createAggregatorNode(config) - Create aggregator node

Pattern Selection Guide

Pattern	Best For	Key Strength	Main Limitation
ReAct	Exploration, flexibility	Dynamic adaptation	Sequential only
Plan-Execute	Structured workflows	Parallel execution	Requires planning
Reflection	Quality-critical outputs	Iterative improvement	Slow, expensive
Multi-Agent	Specialized tasks	Coordinated expertise	High complexity

📚 Pattern Comparison Guide - Detailed guidance on choosing the right pattern

Documentation

• 📖 Full Documentation
• 🚀 Quick Start
• 🤖 ReAct Pattern Guide
• 📋 Plan-Execute Pattern Guide
• 🔄 Reflection Pattern Guide
• 👥 Multi-Agent Pattern Guide
• 💡 Examples

Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Type check
pnpm typecheck

🔗 Links

• GitHub Repository
• npm Package
• Changelog - See what's new before upgrading
• Report Issues

License

MIT © 2026 Tom Van Schoor