Reflection is an agent checkpoint: after acting, the agent examines what it has learned, whether it is still pursuing the goal, and whether its approach should change. Unlike planning, which records what to do next, reflection records an evaluation of progress in the context. The LLM can use that record when choosing its next action. section 7.1.3 section 7.3
Useful checkpoints are:
- Progress review after a meaningful step: record what is complete and what remains. section 7.3.1
- Error analysis after a tool failure: identify the cause and an alternative instead of repeating the failed call. section 7.3.1
- Result synthesis when gathered information needs organizing, especially when sources conflict. section 7.3.1
- Self-check before answering: verify that the required information is present. section 7.3.1
The reflection tool takes free-form analysis and an optional need_replan flag, then returns the analysis as a tool result in the agent’s context. The flag signals that the current plan may need revision. The LLM judges when to call the tool; reflecting after every tool call adds unnecessary overhead, and simple operations can continue without a checkpoint. Reflection checks direction, whereas summarization compresses context to reduce token count. section 7.3.2 section 7.3.1
Listing 7.4 Reflection tool implementation
from scratch_agents.tools import tool
@tool
def reflection(analysis: str, need_replan: bool = False) -> str:
"""Pause and analyze progress before continuing.
WHEN TO USE:
1. PROGRESS REVIEW - After completing a meaningful step
"Kipchoge's record found: 2:01:09. Moving to moon distance research."
2. ERROR ANALYSIS - When a tool fails or returns unexpected results
"Wikipedia tool failed. Cause: service unavailable. Alternative: use web search."
3. RESULT SYNTHESIS - When combining information from multiple sources
"Two different moon distances found. Problem asks for closest approach, so using perigee: 356,500km."
4. SELF CHECK - Before providing final answer
"Have all required data: marathon pace 20.81km/h, moon distance 356,500km. Ready to calculate."
WHEN NOT TO USE:
- After every single tool call (excessive overhead)
- During simple, straightforward operations
- When everything is proceeding as expected
Args:
analysis: Your assessment of current situation and next direction
need_replan: Set True if the current plan needs modification
"""
if need_replan:
return f"Reflection recorded (REPLAN NEEDED): {analysis}"
return f"Reflection recorded: {analysis}"
The Python implementation keeps the mechanism small: a tool description gives the LLM concrete call situations, while the returned analysis becomes available to subsequent decisions. section 7.3.2
Recovering from a failed source
An agent trying to research the Moon’s distance receives a service-unavailable error from a Wikipedia tool. It records a reflection identifying the failure and proposing web search, then can choose search rather than retrying Wikipedia until max_steps. A tool failure may require only a new method: need_replan can remain false if the research goal is unchanged. If new evidence invalidates the task’s premise, setting need_replan to true encourages the agent to revise its plan. section 7.3.3 section 7.4
Planning and reflection form a loop: plan the tasks, execute with tools, check progress, then continue or revise the plan. Reflection can also record that enough search results have been gathered, steering the agent toward an answer instead of another search. section 7.4 section 7.3.4
