Reflexion Agent

The ReflexionAgent implements the Reflexion framework to improve through self-reflection. It follows a process of acting on tasks, evaluating its performance, generating self-reflections, and using these reflections to improve future responses. Based on the research paper: Reflexion: Language Agents with Verbal Reinforcement Learning (Shinn et al., 2023). The agent consists of three specialized sub-agents:

Actor: Generates initial responses to tasks
Evaluator: Critically assesses responses against quality criteria
Reflector: Generates self-reflections to improve future responses

Parameters

Parameter	Type	Default	Description
`agent_name`	`str`	`"reflexion-agent"`	Name of the agent. The sub-agents are named `<agent_name>-actor`, `<agent_name>-evaluator` and `<agent_name>-reflector`
`system_prompt`	`str`	`REFLEXION_PROMPT`	System prompt for the actor. The evaluator and reflector use their own built-in prompts
`model_name`	`str`	`"openai/o1"`	Model name for generating responses
`max_loops`	`int`	`3`	Maximum number of reflection iterations per task
`memory_capacity`	`int`	`100`	Maximum capacity of long-term memory

Methods

act

Generates a response to the given task using the actor agent.

response = agent.act(task: str, relevant_memories: List[Dict[str, Any]] = None) -> str

evaluate

Evaluates the quality of a response to a task. Returns an evaluation string and a score between 0 and 1. The score is the last number after “final score” or “overall score” in the evaluation, divided by 10. If no such number is found, the score is 0.5.

evaluation, score = agent.evaluate(task: str, response: str) -> Tuple[str, float]

reflect

Generates a self-reflection based on the task, response, and evaluation.

reflection = agent.reflect(task: str, response: str, evaluation: str) -> str

refine

Refines the original response based on evaluation and reflection.

refined_response = agent.refine(task: str, original_response: str, evaluation: str, reflection: str) -> str

step

Processes a single task through one iteration of the Reflexion process: it acts (or uses previous_response when given), evaluates, reflects, and stores the result in memory. Returns a dictionary with the keys task, response, evaluation, reflection, score and iteration.

result = agent.step(task: str, iteration: int = 0, previous_response: str = None) -> Dict[str, Any]

run

Executes the full Reflexion process for a list of tasks, one task at a time.

results = agent.run(tasks: List[str], include_intermediates: bool = False) -> List[Any]

For each task, the first iteration acts, evaluates and reflects. Each later iteration refines the previous response with its evaluation and reflection, then evaluates and reflects again. The loop stops after max_loops iterations, or early once a score exceeds 0.9. run() returns one item per task. By default that item is the response with the highest score. With include_intermediates=True it is the list of step() dictionaries for every iteration. Each task and its best response are also added to agent.conversation.

run() takes a list of tasks, not a single string. Wrap a single task in a list.

Example

from swarms import ReflexionAgent

agent = ReflexionAgent(
    agent_name="reflexion-agent",
    model_name="gpt-5.4",
    max_loops=3
)

tasks = [
    "Explain quantum computing to a beginner.",
    "Write a Python function to sort a list of dictionaries by a specific key."
]

results = agent.run(tasks)

for i, result in enumerate(results):
    print(f"\nTask {i+1}: {tasks[i]}")
    print(f"Response: {result}")

Memory System

The agent includes a ReflexionMemory system that maintains both short-term and long-term memories of past experiences, reflections, and feedback.

Short-term memory keeps the 10 most recent step() results.
Long-term memory receives a step’s result when its score is above 0.8 or it is the last iteration. It holds up to memory_capacity entries and drops the oldest first.
Deduplication skips a long-term entry when the words of its task and reflection have a Jaccard similarity above 0.8 with an existing entry.
Retrieval with agent.memory.get_relevant_memories(task, limit=5) ranks short-term and long-term entries by the words they share with the task.

act() adds the reflections from relevant_memories to the actor’s prompt. Inside run(), refinement works from the previous iteration’s evaluation and reflection rather than from retrieved memories.

Best Practices

Task Clarity: Provide clear, specific tasks to get the best results
Iteration Count: Adjust max_loops based on task complexity (more complex tasks benefit from more iterations)
Memory Management: Monitor memory usage and adjust memory_capacity as needed
Model Selection: Choose an appropriate model based on your specific use case

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

Reflexion Agent

Parameters

Methods

act

evaluate

reflect

refine

step

run

Example

Memory System

Best Practices

​Parameters

​Methods

​act

​evaluate

​reflect

​refine

​step

​run

​Example

​Memory System

​Best Practices

Parameters

Methods

act

evaluate

reflect

refine

step

run

Example

Memory System

Best Practices