Skip to main content

​
@agentlib/reasoning

Reasoning engines for AgentLIB — powerful strategies for agent decision-making and problem-solving.

​
Installation

npm install @agentlib/reasoning

​
Overview

The @agentlib/reasoning package provides five built-in reasoning engines:
  • ReAct: Reason + Act pattern for tool-using agents
  • Chain-of-Thought (CoT): Step-by-step reasoning before responding
  • Planner: Task decomposition and sequential execution
  • Reflect: Self-reflection and answer revision
  • Autonomous: Fully autonomous multi-step reasoning
All engines are automatically registered when you import the package, allowing you to use them by name.

​
Quick Start

import { createAgent } from '@agentlib/core'
import '@agentlib/reasoning' // Auto-registers all engines

const agent = createAgent({
  name: 'assistant',
  reasoning: 'react' // Use by name
})

​
Reasoning Engines

​
ReAct Engine

The ReAct (Reason + Act) pattern alternates between reasoning and action steps. Perfect for tool-using agents. 
import { ReactEngine } from '@agentlib/reasoning'

const agent = createAgent({
  name: 'assistant',
  reasoning: 'react',
  tools: [searchTool, calculatorTool]
})

// Or use directly
const agent = createAgent({
  name: 'assistant',
  reasoning: new ReactEngine({ maxIterations: 10 })
})
Configuration: 
interface ReactEngineConfig {
  /** Maximum reasoning iterations (default: 10) */
  maxIterations?: number
  
  /** Custom prompt template */
  prompt?: string
}
How it works:
  1. Receives user input
  2. Generates thought + action (tool call)
  3. Executes tool and observes result
  4. Repeats until final answer
  5. Returns response
Best for:
  • Agents with tools
  • Question answering with external data
  • Research and information gathering

​
Chain-of-Thought Engine

The Chain-of-Thought (CoT) engine guides the model through explicit reasoning steps before providing a final answer. 
import { ChainOfThoughtEngine } from '@agentlib/reasoning'

const agent = createAgent({
  name: 'assistant',
  reasoning: 'cot'
})

// With custom configuration
const agent = createAgent({
  name: 'assistant',
  reasoning: new ChainOfThoughtEngine({
    steps: 5,
    prompt: 'Think step by step:'
  })
})
Configuration: 
interface ChainOfThoughtEngineConfig {
  /** Number of reasoning steps (default: 3) */
  steps?: number
  
  /** Custom reasoning prompt */
  prompt?: string
}
How it works:
  1. Breaks down the problem
  2. Generates intermediate reasoning steps
  3. Synthesizes final answer
Best for:
  • Math problems
  • Logical reasoning
  • Complex question answering
  • Educational applications

​
Planner Engine

The Planner engine decomposes tasks into subtasks and executes them sequentially. 
import { PlannerEngine } from '@agentlib/reasoning'

const agent = createAgent({
  name: 'assistant',
  reasoning: 'planner',
  tools: [researchTool, writeTool, reviewTool]
})

// With configuration
const agent = createAgent({
  name: 'assistant',
  reasoning: new PlannerEngine({
    maxTasks: 10,
    allowDependencies: true
  })
})
Configuration: 
interface PlannerEngineConfig {
  /** Maximum number of subtasks (default: 10) */
  maxTasks?: number
  
  /** Allow task dependencies (default: true) */
  allowDependencies?: boolean
  
  /** Custom planning prompt */
  prompt?: string
}
How it works:
  1. Analyzes the user request
  2. Generates a plan with subtasks
  3. Executes tasks in order (respecting dependencies)
  4. Synthesizes results into final answer
Emitted steps:
  • type: 'plan' - The generated plan
  • type: 'tool_call' - Each subtask execution
  • type: 'tool_result' - Subtask results
  • type: 'response' - Final answer
Best for:
  • Complex multi-step tasks
  • Research projects
  • Content creation workflows
  • Project management

​
Reflect Engine

The Reflect engine generates an answer, critiques it, and optionally revises it. 
import { ReflectEngine } from '@agentlib/reasoning'

const agent = createAgent({
  name: 'assistant',
  reasoning: 'reflect'
})

// With configuration
const agent = createAgent({
  name: 'assistant',
  reasoning: new ReflectEngine({
    maxRevisions: 3,
    reflectionPrompt: 'Critique your previous answer:'
  })
})
Configuration: 
interface ReflectEngineConfig {
  /** Maximum number of revision cycles (default: 2) */
  maxRevisions?: number
  
  /** Custom reflection prompt */
  reflectionPrompt?: string
  
  /** Custom revision prompt */
  revisionPrompt?: string
}
How it works:
  1. Generates initial answer
  2. Reflects on the answer quality
  3. If revision needed, generates improved version
  4. Repeats up to maxRevisions times
  5. Returns final answer
Emitted steps:
  • type: 'response' - Initial answer
  • type: 'reflection' - Self-critique
  • type: 'response' - Revised answer (if needed)
Best for:
  • High-quality content generation
  • Code review and improvement
  • Essay writing
  • Critical thinking tasks

​
Autonomous Engine

The Autonomous engine runs fully independently, deciding when to use tools, when to think, and when to respond. 
import { AutonomousEngine } from '@agentlib/reasoning'

const agent = createAgent({
  name: 'assistant',
  reasoning: 'autonomous',
  tools: [searchTool, calculatorTool, writeTool]
})

// With configuration
const agent = createAgent({
  name: 'assistant',
  reasoning: new AutonomousEngine({
    maxSteps: 20,
    allowParallelTools: true
  })
})
Configuration: 
interface AutonomousEngineConfig {
  /** Maximum total steps (default: 15) */
  maxSteps?: number
  
  /** Allow parallel tool execution (default: false) */
  allowParallelTools?: boolean
  
  /** Custom system prompt */
  systemPrompt?: string
}
How it works:
  1. Agent decides its own action strategy
  2. Can call multiple tools, think, or respond
  3. Continues until it determines task is complete
  4. Returns final answer
Best for:
  • Open-ended tasks
  • Complex problem solving
  • Research and exploration
  • When you want minimal guidance

​
Auto-Registration

All engines are automatically registered when you import @agentlib/reasoning: 
import '@agentlib/reasoning'

// Now you can use string names
agent.reasoning('react')
agent.reasoning('planner')
agent.reasoning('cot')
agent.reasoning('reflect')
agent.reasoning('autonomous')
This happens because the package runs: 
import { registerEngine } from '@agentlib/core'

registerEngine('react', () => new ReactEngine())
registerEngine('planner', () => new PlannerEngine())
registerEngine('cot', () => new ChainOfThoughtEngine())
registerEngine('reflect', () => new ReflectEngine())
registerEngine('autonomous', () => new AutonomousEngine())

​
Custom Reasoning Engines

You can create your own reasoning engines: 
import { ReasoningEngine, ReasoningContext } from '@agentlib/core'

class MyCustomEngine implements ReasoningEngine {
  readonly name = 'custom'
  
  async execute(rCtx: ReasoningContext): Promise<string> {
    // Your reasoning logic here
    rCtx.pushStep({
      type: 'thought',
      content: 'Thinking...',
      engine: 'custom'
    })
    
    // Call the model
    const response = await rCtx.model.complete({
      messages: rCtx.ctx.state.messages
    })
    
    return response.message.content
  }
}

// Register it
import { registerEngine } from '@agentlib/core'
registerEngine('custom', () => new MyCustomEngine())

// Use it
agent.reasoning('custom')

​
Reasoning Steps

All engines emit reasoning steps that you can observe: 
agent.on('step:reasoning', (step) => {
  console.log(`[${step.engine}] ${step.type}:`, step)
})
Step types:
  • thought - Reasoning/thinking step
  • plan - Generated plan with subtasks
  • tool_call - Tool invocation
  • tool_result - Tool execution result
  • reflection - Self-critique
  • response - Final or intermediate answer

​
Comparing Engines

EngineBest ForComplexityTool UseIterations
ReActTool-heavy tasksMediumYesMulti
CoTReasoning tasksLowNoSingle
PlannerMulti-step projectsHighYesMulti
ReflectQuality improvementMediumNoMulti
AutonomousOpen-ended tasksHighYesMulti

​
Requirements

  • Node.js: >= 18.0.0
  • Dependencies: @agentlib/core (workspace)

​
Exports

​
Engines

  • ReactEngine
  • ChainOfThoughtEngine
  • PlannerEngine
  • ReflectEngine
  • AutonomousEngine

​
Types

  • ReactEngineConfig
  • ChainOfThoughtEngineConfig
  • PlannerEngineConfig
  • ReflectEngineConfig
  • AutonomousEngineConfig

Build docs developers (and LLMs) love

Get started for freeTalk to us