中文版

🚀 General-Evolve General Evolve Agent Efficient,stable driving of universal algorithm design and continuous evolution.

🔥 ML-Evolve Machine Learning Agent Full-process,autonomous construction and continuous evolutionary breakthrough.

⭐ LoongFlow Universal Agent Framework A Universal Agent Framework for Expert-Grade AI Productivity.

LoongFlow: Inspired by Wang Yangming's "Enlightenment at Longchang".LoongFlow is dedicated to breaking the barrier between Knowing and Doing. We enable wisdom to awaken through the unity of knowledge and action, ensuring that every drop of professional expertise is transformed into powerful AI productivity.

An expert-grade Agent framework that thinks and learns. It empowers Agents to think like scientists, helping developers rapidly transform their professional expertise into expert-level Agents.

• Intelligent Thinking: Innovative PES (Planning-Execution-Summary) Paradigm. LoongFlow empowers Agents with structured thinking to tackle long-range complex reasoning challenges. This enables Agents to iterate through high-difficulty tasks with the rigorous mindset of a human scientist.
• Continuous Learning: Innovative Multi-Structure Fusion Memory. By actively generating model reasoning contexts, LoongFlow allows Agents to continuously synthesize experience during task iterations. This results in a "run-and-improve" mechanism, achieving lightweight learning and evolution without heavy retraining.

We believe that the key to designing an expert-level Agent capable of solving complex problems lies in the Agent’s thinking paradigm. The thinking paradigm determines the complexity of problems an Agent can handle and sets the ceiling for its effectiveness. LoongFlow is built specifically for complex tasks requiring long-range reasoning, helping developers rapidly build Agents with domain-expert performance.

LoongFlow requires Python 3.12 or higher.

# Install uv/conda and clone repository
uv: https://docs.astral.sh/uv/getting-started/installation/
Miniforge: https://conda-forge.org/download/

# Install with uv
cd LoongFlow
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e .

# Install with conda
cd LoongFlow
conda create -n loongflow python=3.12
conda activate loongflow
pip install -e .

# Config LLM: Edit task_config.yaml, recommend to use gemini-3-pro-preview or deepseek-r1-250528
# Example: ./agents/general_evolve/examples/packing_circle_in_unit_square/task_config.yaml
# The model needs to configure providers as needed, default provider is openai. for example: openai/gemini-3-pro-preview
llm_config:
  url: "https://xxxxxx/v1"
  api_key: "******"
  model: "openai/gemini-3-pro-preview"

# Run your first evolve task, the evolution results are in the ./output directory
uv pip install -r ./agents/general_evolve/examples/packing_circle_in_unit_square/requirements.txt
./run_task.sh packing_circle_in_unit_square --background

# Check task log
tail -f ./agents/general_evolve/examples/packing_circle_in_unit_square/run.log

# Stop task
./run_task.sh stop packing_circle_in_unit_square

# Config LLM: Edit task_config.yaml, recommend to use gemini-3-pro-preview or deepseek-r1-250528
# Example: ./agents/ml_evolve/examples/ml_example/task_config.yaml
# The model needs to configure providers as needed, default provider is openai. for example: openai/gemini-3-pro-preview
llm_config:
  url: "https://xxxxxx/v1"
  api_key: "******"
  model: "openai/gemini-3-pro-preview"

# Init ml evolve
./run_ml.sh init

# Run your first evolve task, the evolution results are in the ./output directory
# ./run_ml.sh run <task_name> [--background] [other Python args]
./run_ml.sh run ml_example --background

# Check task log
tail -f ./agents/ml_evolve/examples/ml_example/agent.log

# Stop task
./run_ml.sh stop ml_example

LoongFlow is designed around a simple idea:

Expert-level performance emerges not from better mutations, but from better thinking, reflection, and accumulated experience.

To achieve this, LoongFlow organizes agent behavior into a thinking–learning–evolving loop.

From Evolutionary Agents to Thinking Agents

Frameworks such as OpenEvolve and AlphaEvolve demonstrated that agents can improve through iteration, evaluation, and selection.

This marked a clear step beyond static prompting.

However, in real-world expert tasks, purely evolutionary loops often struggle because:

• Exploration is blind or weakly guided
• Long-horizon reasoning breaks easily
• Experience remains task-specific
• Agents converge prematurely to local optima

The core issue is not evolution itself, but the lack of a structured thinking process.

LoongFlow addresses this by shifting the abstraction:

from evolving outputs to standardizing how agents think, act, and learn.

At the core of LoongFlow is the PES (Plan–Execute–Summary) thinking paradigm, inspired by how human experts conduct research:

Each agent iteration follows the same explicit structure:

PES transforms evolution from a mutation-driven process into a reasoning-guided improvement loop.

Thinking alone is not enough. To improve over time, agents must remember, generalize, and escape local optima.

LoongFlow integrates PES with a hybrid evolutionary memory system:

• Multi-Island + MAP-Elites to preserve diversity
• Adaptive Boltzmann selection to balance exploration and exploitation
• Global evolutionary tree memory for long-range experience retrieval

This allows agents to perform jump-style reasoning — leveraging past discoveries to move beyond incremental local search.

Across 11 challenges in geometry and algebra, LoongFlow outperformed all known best results and surpassed AlphaEvolve on 7 specific problems, achieving the latest SOTA.

Validated across 40 Kaggle competitions within the MLE-bench, securing 22 Gold Medals. The full results will be released upon the completion of all remaining competitions.

Additionally, validation was conducted on problems such as mathematical puzzles and MOE load balancing algorithms，Detailed examples can be found in Examples.

from evolux.evolve import EvolveAgent

# Config evolve agent
agent = EvolveAgent(
    config=config,
    checkpoint_path=checkpoint_path,
)

# Register worker（Implement the Planner, Executor, and Summary interfaces）
agent.register_planner_worker("planner", PlanAgent)
agent.register_executor_worker("executor", ExecuteAgent)
agent.register_summary_worker("summary", SummaryAgent)

# Run agent
result = await agent()

For more details, please refer to EvolveAgent

from evolux.react import AgentContext, ReActAgent
from agentsdk.tools import TodoReadTool, TodoWriteTool, Toolkit

# Build agent context
toolkit = Toolkit()
toolkit.register_tool(TodoReadTool())
toolkit.register_tool(TodoWriteTool())

# Build default react agent
agent = ReActAgent.create_default(model=model, sys_prompt=sys_prompt, toolkit=toolkit)

# Run agent
result = await agent(message)

For more details, please refer to ReActAgent

Real-time evolution tracking with interactive web interface:

# Launch visualization server
python agents/general_evolve/visualizer/visualizer.py --port 8888 --checkpoint-path output-circle-packing/database/checkpoints

Features:

• 🌳 Evolution tree with parent-child relationships
• 📈 Performance tracking across generations
• 🔍 Code diff viewer showing mutations
• 📊 Island map for visualizing the distribution of solutions

We welcome contributions! Here's how to get started:

1. 🍴 Fork the repository
2. 🌿 Create your feature branch: git checkout -b feat-amazing-feature
3. ✨ Add your changes and tests
4. 📝 Commit with a clear message
5. 🚀 Push and create a Pull Request

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Welcome to join our community on

Discord	Wechat

LoongFlow is licensed under the Apache License 2.0.

If you find this work useful, please consider citing:

@misc{LoongFlow2025,
      title={LoongFlow: Directed Evolutionary Search via a Cognitive Plan-Execute-Summarize Paradigm}, 
      author={Chunhui Wan and Xunan Dai and Zhuo Wang and Minglei Li and Yanpeng Wang and Yinan Mao and Yu Lan and Zhiwen Xiao},
      year={2025},
      eprint={2512.24077},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2512.24077}, 
}