Agent patterns (ReAct, Planner-Executor) for AgentForge framework
npm install @agentforge/patterns> Production-ready agent patterns for the AgentForge framework
All 4 patterns complete | 143 tests passing | Full TypeScript support | Comprehensive documentation
The ReAct pattern implements a thought-action-observation loop for exploratory tasks:
1. Think - Reason about what to do next
2. Act - Execute a tool or provide final answer
3. Observe - Process the result
4. 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
The Plan-Execute pattern separates planning from execution for complex, structured tasks:
1. Plan - Create a multi-step plan
2. Execute - Execute each step (sequential or parallel)
3. Replan (optional) - Adjust based on results
4. 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
The Reflection pattern implements iterative self-improvement through critique and revision:
1. Generate - Create initial response
2. Reflect - Critique the output
3. Revise - Improve based on critique
4. 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
The Multi-Agent pattern coordinates multiple specialized agents for complex tasks:
1. Supervisor - Routes tasks to workers
2. Workers - Execute specialized tasks
3. Aggregator - Combines results
4. 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
``bash`
pnpm add @agentforge/patterns @agentforge/core
Simple reasoning and action loop:
`typescript
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"
`
Structured planning and execution:
`typescript
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() }),
execute: async ({ query }) => {
// Search implementation
return { results: [...] };
},
};
const analyzeTool = {
name: 'analyze',
description: 'Analyze data',
schema: z.object({ data: z.any() }),
execute: async ({ data }) => {
// Analysis implementation
return { insights: [...] };
},
};
// Create the agent
const agent = createPlanExecuteAgent({
planner: {
llm: new ChatOpenAI({ model: 'gpt-4' }),
maxSteps: 5,
},
executor: {
tools: [searchTool, analyzeTool],
parallel: true, // Enable parallel execution
},
replanner: {
llm: 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
`
Iterative self-improvement:
`typescript
import { createReflectionAgent } from '@agentforge/patterns';
import { ChatOpenAI } from '@langchain/openai';
// Create the agent
const agent = createReflectionAgent({
generator: {
llm: new ChatOpenAI({ model: 'gpt-4' }),
systemPrompt: 'You are a professional writer. Create high-quality content.',
},
reflector: {
llm: new ChatOpenAI({ model: 'gpt-4' }),
systemPrompt: 'Critique the content for clarity, engagement, and professionalism.',
},
maxIterations: 3,
verbose: true,
});
// Use the agent
const result = await agent.invoke({
messages: [{ role: 'user', content: 'Write a blog post about AI' }],
});
console.log(result.reflections); // All critiques
console.log(result.response); // Final refined response
`
Coordinate specialized agents:
`typescript
import { MultiAgentSystemBuilder } from '@agentforge/patterns';
import { ChatOpenAI } from '@langchain/openai';
const llm = new ChatOpenAI({ model: 'gpt-4' });
// Create builder
const builder = new MultiAgentSystemBuilder({
supervisor: {
llm,
strategy: 'skill-based', // or 'llm-based', 'round-robin', etc.
},
aggregator: { llm },
});
// Register specialized workers
builder.registerWorkers([
{
id: 'tech_support',
name: 'Tech Support',
description: 'Handles technical issues',
capabilities: {
skills: ['technical', 'troubleshooting', 'debugging'],
tools: ['diagnostic', 'troubleshoot'],
available: true,
},
llm,
tools: [diagnosticTool, troubleshootTool],
},
{
id: 'billing_support',
name: 'Billing Support',
description: 'Handles billing inquiries',
capabilities: {
skills: ['billing', 'payments', 'refunds'],
tools: ['account_check', 'refund_process'],
available: true,
},
llm,
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
`
`typescript`
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
`typescript`
import {
createPlanExecuteAgent,
createPlannerNode,
createExecutorNode,
createReplannerNode,
createFinisherNode,
} from '@agentforge/patterns';
Main API:
- createPlanExecuteAgent(config) - Create a complete Plan-Execute agent
Configuration:
`typescript`
{
planner: {
llm: BaseChatModel, // LLM for planning
systemPrompt?: string, // Custom planning prompt
maxSteps?: number, // Max steps in plan (default: 10)
includeToolDescriptions?: boolean,
},
executor: {
tools: Tool[], // Available tools
llm?: BaseChatModel, // Optional LLM for sub-tasks
parallel?: boolean, // Enable parallel execution
stepTimeout?: number, // Timeout per step (ms)
maxParallelSteps?: number, // Max concurrent steps
},
replanner?: {
llm: BaseChatModel, // LLM for replanning
replanThreshold?: number, // Confidence threshold (0-1)
systemPrompt?: string, // Custom replanning prompt
},
maxIterations?: number, // Max planning iterations
returnIntermediateSteps?: boolean,
verbose?: boolean,
}
Node Creators (for custom workflows):
- createPlannerNode(config) - Create planner nodecreateExecutorNode(config)
- - Create executor nodecreateReplannerNode(config)
- - Create replanner nodecreateFinisherNode()
- - Create finisher node
`typescript`
import {
createReflectionAgent,
createGeneratorNode,
createReflectorNode,
createReviserNode,
} from '@agentforge/patterns';
Main API:
- createReflectionAgent(config) - Create a complete Reflection agent
Configuration:
`typescript`
{
generator: {
llm: BaseChatModel, // LLM for generation
systemPrompt?: string, // Custom generation prompt
},
reflector: {
llm: BaseChatModel, // LLM for reflection
systemPrompt?: string, // Custom reflection prompt
criteria?: string[], // Reflection criteria
},
maxIterations?: number, // Max reflection cycles (default: 3)
qualityThreshold?: number, // Quality score threshold (0-1)
returnIntermediateSteps?: boolean,
verbose?: boolean,
}
Node Creators (for custom workflows):
- createGeneratorNode(config) - Create generator nodecreateReflectorNode(config)
- - Create reflector nodecreateReviserNode(config)
- - Create reviser node
`typescript`
import {
createMultiAgentSystem,
registerWorkers,
createSupervisorNode,
createWorkerNode,
createAggregatorNode,
} from '@agentforge/patterns';
Main API:
- createMultiAgentSystem(config) - Create a complete Multi-Agent systemregisterWorkers(system, workers)
- - Register workers with the system
Configuration:
`typescript`
{
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:
`typescript`
{
name: string, // Unique worker identifier
description: string, // Worker description
capabilities: string[], // Worker capabilities/skills
tools: Tool[], // Available tools
systemPrompt?: string, // Worker-specific prompt
}
Node Creators (for custom workflows):
- createSupervisorNode(config) - Create supervisor nodecreateWorkerNode(config)
- - Create worker nodecreateAggregatorNode(config)
- - Create aggregator node
| 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
- š Full Documentation
- š Quick Start
- š¤ ReAct Pattern Guide
- š Plan-Execute Pattern Guide
- š Reflection Pattern Guide
- š„ Multi-Agent Pattern Guide
- š” Examples
`bashInstall dependencies
pnpm install
- GitHub Repository
- npm Package
- Changelog - See what's new before upgrading
- Report Issues
MIT Ā© 2026 Tom Van Schoor