Skip to main content
The Reflection Agent analyzes completed MAX-level tasks and hypothesis to extract key insights, update the research objective, and refine methodology. It maintains the “world state” that guides future iterations.

​
Function Signature

// src/agents/reflection/index.ts
export async function reflectionAgent(input: {
  conversationState: ConversationState;
  message: Message;
  completedMaxTasks: PlanTask[];
  hypothesis?: string;
}): Promise<ReflectionResult>;

type ReflectionResult = {
  conversationTitle?: string;
  evolvingObjective?: string;
  currentObjective?: string;
  keyInsights: string[];
  methodology?: string;
  discoveries?: Discovery[];  // Deprecated - now handled by Discovery Agent
  start: string;
  end: string;
};

​
What It Does

​
Extracts Key Insights

Identifies important findings from completed tasks: 
const result = await reflectionAgent({
  conversationState,
  message,
  completedMaxTasks: [
    {
      type: "LITERATURE",
      output: "(p53 regulates senescence via p21)[10.1038/nature...]..."
    },
    {
      type: "ANALYSIS",
      output: "p21 expression increased 3.2-fold (p < 0.001)..."
    }
  ],
  hypothesis: "p53-p21 axis regulates cellular senescence"
});

// Returns:
// {
//   keyInsights: [
//     "p53 directly activates p21 transcription in response to stress",
//     "p21 expression shows 3.2-fold increase in senescent cells",
//     "p53-p21 axis confirmed as primary senescence regulator"
//   ]
// }

​
Updates Current Objective

Refines the research focus based on findings: 
// Initial objective:
"Investigate mechanisms of cellular senescence"

// After reflection:
"Investigate downstream targets of p53-p21 axis and their role in SASP activation"

​
Refines Methodology

Suggests methodological improvements: 
// {
//   methodology: "Use RNA-seq to identify p21 downstream targets. Perform knockdown experiments to validate p53-p21 dependency. Measure SASP factor secretion."
// }

​
Usage Example

// src/routes/deep-research/start.ts
const reflectionResult = await reflectionAgent({
  conversationState,
  message,
  completedMaxTasks,
  hypothesis: hypothesisText
});

// Update conversation state
conversationState.values.currentObjective = reflectionResult.currentObjective;
conversationState.values.keyInsights = reflectionResult.keyInsights;
conversationState.values.methodology = reflectionResult.methodology;

if (reflectionResult.conversationTitle) {
  await updateConversation(conversationId, {
    title: reflectionResult.conversationTitle
  });
}

await updateConversationState(
  conversationState.id,
  conversationState.values
);

​
World State Updates

The Reflection Agent updates specific fields in ConversationState:
​
currentObjective
string
Current research focus for next iteration
​
keyInsights
string[]
Important findings accumulated across iterations
​
methodology
string
Suggested experimental or analytical approaches
​
conversationTitle
string
Auto-generated title summarizing the research (optional)
See State Management for complete schema.

​
Integration with Discovery Agent

Previously, the Reflection Agent handled discovery extraction. This is now delegated to the Discovery Agent: 
// Old: Reflection handled discoveries
const reflectionResult = await reflectionAgent(...);
conversationState.values.discoveries = reflectionResult.discoveries;

// New: Separate discovery agent
const reflectionResult = await reflectionAgent(...);
const discoveryResult = await discoveryAgent({
  conversationState,
  message,
  tasksToConsider: completedMaxTasks,
  hypothesis
});
conversationState.values.discoveries = discoveryResult.discoveries;

​
Reflection Prompts

The agent uses structured prompts to extract insights: 
// src/agents/reflection/prompts.ts
export const REFLECTION_PROMPT = `
You are a scientific reflection agent...

Your task:
1. Review completed tasks and hypothesis
2. Extract 3-5 key insights
3. Update current objective for next iteration
4. Suggest methodological improvements
...
`;

​
Configuration

​
STRUCTURED_LLM_PROVIDER
string
default:"openai"
LLM provider: openai, anthropic, google, or openrouter
​
STRUCTURED_LLM_MODEL
string
default:"gpt-5"
Model name for reflection agent

​
Example Flow

1

Initial state

{
  "currentObjective": "Investigate cellular senescence",
  "keyInsights": []
}
2

After first iteration

{
  "currentObjective": "Investigate p53-p21 axis in senescence",
  "keyInsights": [
    "p53 regulates senescence via p21 activation"
  ]
}
3

After second iteration

{
  "currentObjective": "Investigate SASP factors downstream of p21",
  "keyInsights": [
    "p53 regulates senescence via p21 activation",
    "p21 expression correlates with SASP marker IL-6",
    "mTOR pathway involved in SASP regulation"
  ],
  "methodology": "Use RNA-seq and ELISA to measure SASP factors..."
}

Hypothesis Agent

Generates hypotheses from tasks

Discovery Agent

Extracts novel scientific claims

State Management

Understand world state schema

Build docs developers (and LLMs) love

Get started for freeTalk to us