ReflectEngine

​

Overview

​

When to Use

• Accuracy and quality are more important than speed
• Answers require careful validation or fact-checking
• You want the model to self-correct mistakes
• Tasks involve writing, analysis, or decision-making that benefits from revision
• You need transparent quality assessment

​

Constructor

import { ReflectEngine } from '@agentlib/reasoning'

const engine = new ReflectEngine(config)

​

Configuration

​

Usage Example

import { Agent } from '@agentlib/core'
import { ReflectEngine } from '@agentlib/reasoning'
import { searchTool, calculatorTool } from './tools'

const agent = new Agent({
  name: 'research-analyst',
  model: myModelProvider,
  tools: [searchTool, calculatorTool],
  reasoning: new ReflectEngine({
    maxReflections: 3,
    acceptanceThreshold: 9 // Stricter quality bar
  })
})

const result = await agent.run({
  input: 'Analyze the pros and cons of renewable energy adoption in developing countries'
})

​

How It Works

​

Phase 1: Generate Initial Answer

1. Model receives the user input and generates an initial response
2. Can use tools during generation (up to maxAnswerSteps)
3. Initial answer is extracted and stored

​

Phase 2: Reflection Loop

1. Critique: Send answer to model with critique prompt
2. Parse: Extract JSON critique with score, issues, and suggestions
3. Evaluate: Check if score >= acceptanceThreshold or needs_revision is false
4. Decide:
   • If acceptable: break loop and return answer
   • If not acceptable: proceed to revision

​

Phase 3: Revise

1. Model receives original question, current answer, and critique
2. Generates improved answer (may use tools)
3. Updated answer becomes the current answer
4. Loop continues with another critique

​

Critique Response Schema

{
  "score": 7,
  "issues": [
    "Missing data on infrastructure challenges",
    "Could expand on economic barriers"
  ],
  "suggestion": "Add specific examples from sub-Saharan Africa and Southeast Asia",
  "needs_revision": true
}

​

Step Emissions

• ThoughtStep: Emitted after initial answer generation and before each revision
• ReflectionStep: Emitted after each critique with assessment and revision decision
• ToolCallStep / ToolResultStep: Emitted during answer generation/revision tool usage
• ResponseStep: Emitted with the final accepted answer

​

Example Reflection Step

{
  "type": "reflection",
  "assessment": "Score: 7/10. Issues: Missing data on infrastructure challenges; Could expand on economic barriers. Add specific examples from sub-Saharan Africa and Southeast Asia",
  "needsRevision": true,
  "engine": "reflect"
}

​

Default Critique Prompt

You are a critical evaluator. Review the answer below and assess its quality.

Respond in this exact JSON format (no markdown):
{
  "score": <0-10>,
  "issues": ["<issue 1>", "<issue 2>"],
  "suggestion": "<one-sentence improvement suggestion>",
  "needs_revision": <true|false>
}

Be strict. Score 10 only for perfect answers. Score < 8 if the answer is incomplete, incorrect, or could be substantially improved.

​

Error Handling

[ReflectEngine] Max answer steps (5) reached.

​

Performance Considerations

• Slower than ReactEngine: Multiple model calls per reflection cycle
• Higher token usage: Critiques and revisions add overhead
• Quality tradeoff: Better answers at the cost of latency

​

String Alias

const agent = new Agent({
  name: 'my-agent',
  reasoning: 'reflect' // Uses default ReflectEngine
})

​

Implementation Reference