### Install Example Dependencies and Run Math Agent Task

Source: https://github.com/baidu-baige/loongflow/blob/main/CLAUDE.md

Install dependencies for a specific math agent example and run its task in the background. Check logs using tail.

```bash
uv pip install -r ./agents/math_agent/examples/packing_circle_in_unit_square/requirements.txt
./run_math.sh packing_circle_in_unit_square --background
tail -f ./agents/math_agent/examples/packing_circle_in_unit_square/run.log
./run_math.sh stop packing_circle_in_unit_square
```

--------------------------------

### Environment Setup

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Steps to set up the project environment, including creating a virtual environment and installing dependencies.

```bash
cd LoongFlow

uv venv .venv --python 3.12
source .venv/bin/activate

uv pip install -e .
```

--------------------------------

### Run the TODO List Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/examples/01_todo_list/README.md

Navigate to the LoongFlow root, set your API keys, and run the example script to start the TODO list application generation process.

```bash
# 1. Navigate to LoongFlow root
cd /path/to/LoongFlow

# 2. Set your API keys (if not already set)
export ANTHROPIC_API_KEY="your-key"
export ANTHROPIC_BASE_URL="your-endpoint"

# 3. Run the example
./run_general.sh 01_todo_list
```

--------------------------------

### Setup Python Environment with uv

Source: https://github.com/baidu-baige/loongflow/blob/main/AGENTS.md

Installs Python 3.12, creates a virtual environment, and installs the project dependencies using uv.

```bash
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e .
```

--------------------------------

### Run General Evolve Agent Example

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/build_agent/get_started.md

Install dependencies, run, view logs, and stop a General Evolve Agent example.

```bash
# Install example dependencies
uv pip install -r ./agents/general_evolve/examples/packing_circle_in_unit_square/requirements.txt

# Run example (background mode)
./run_task.sh packing_circle_in_unit_square --background

# View run logs
tail -f ./agents/general_evolve/examples/packing_circle_in_unit_square/run.log

# Stop task
./run_task.sh stop packing_circle_in_unit_square
```

--------------------------------

### Start a New Task with General Agent

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Navigate to the LoongFlow directory and execute the run script to start your first task, using '01_todo_list' as an example task name.

```bash
cd LoongFlow
./run_general.sh 01_todo_list
```

--------------------------------

### Initial Program Example

Source: https://github.com/baidu-baige/loongflow/blob/main/src/loongflow/framework/pes/README.md

Provides a valid starting solution for an evolutionary task. It must include the entry point function expected by the evaluator.

```python
import numpy as np

def solve():
    """Initial valid (but likely suboptimal) solution."""
    return np.array([0, 0, 0])
```

--------------------------------

### Run Machine Learning Agent Example

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/build_agent/get_started.md

Initialize the ML environment, run an ML example, view logs, and stop the task.

```bash
# Initialize ML environment
./run_ml.sh init

# Run ML example
./run_ml.sh run ml_example --background

# View run logs
tail -f ./agents/ml_evolve/examples/ml_example/agent.log

# Stop task
./run_ml.sh stop ml_example
```

--------------------------------

### Run Example Tasks

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Commands to run different example tasks, including options for background execution and custom configurations.

```bash
./run_general.sh 01_todo_list

./run_general.sh 02_file_processor

./run_general.sh 01_todo_list --background

./run_general.sh 01_todo_list --log-level DEBUG --max-iterations 50
```

--------------------------------

### Setup Python Environment with uv

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/agents/ml_evolve.md

Installs the ML Evolve Agent and its dependencies using `uv` for Python 3.12+.

```bash
# Execute in the project root directory
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e .
```

--------------------------------

### Run Basic Installation Tests

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/build_agent/get_started.md

Execute the basic tests using `pytest` to verify the installation and setup of LoongFlow.

```bash
uv run pytest tests/ -v
```

--------------------------------

### Initial Program Code Example

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/agents/general_evolve.md

Python code for the initial solution framework. This serves as the starting point for the evolutionary process.

```python
# EVOLVE-BLOCK-START
"""Your initial algorithm implementation"""
import numpy as np

def your_initial_solution(problem_parameters):
    # Basic implementation; the evolution process will improve upon this
    return solution

# EVOLVE-BLOCK-END
```

--------------------------------

### Run Example Task

Source: https://github.com/baidu-baige/loongflow/blob/main/src/loongflow/framework/pes/README.md

Execute a built-in example task for packing circles in a unit square. Results are saved to the ./output directory. Use the stop command to halt the task.

```bash
# Run the example task (results will be in ./output)
./run_math.sh packing_circle_in_unit_square --background

# Stop the task
./run_math.sh stop packing_circle_in_unit_square
```

--------------------------------

### Set Up Environment with uv

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/overview/quickstart.md

Create a virtual environment using uv, activate it, and install LoongFlow and its dependencies.

```bash
# Create virtual environment
uv venv .venv --python 3.12
source .venv/bin/activate

# Install dependencies
uv pip install -e .
```

--------------------------------

### Basic Configuration Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Example of a basic configuration file for the General Agent, including workspace, LLM, and evolution settings.

```yaml
workspace_path: "./output-task-name"

llm_config:
  model: "anthropic/model-name"
  url: "https://api.anthropic.com"
  api_key: "xxx"

evolve:
  task: |
    You are an expert software developer. Your task is to iteratively improve existing codebase.
    Specific goal: Develop an efficient data processing system.
  max_iterations: 100
  target_score: 0.9
  concurrency: 5
```

--------------------------------

### Task Configuration File Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Example of a task_config.yaml file, specifying workspace, LLM, skills, and task evolution parameters.

```yaml
workspace_path: "./output-my-task"
llm_config:
  model: "anthropic/deepseek-v3.2"

planners:
  general_planner:
    skills: ["skill-creator"]
    max_turns: 10

executors:
  general_executor:
    skills: ["skill-creator"]

summarizers:
  general_summarizer:
    max_turns: 10

evolve:
  task: |
    Develop an efficient data analysis system that can process CSV files and perform basic statistical analysis.
  max_iterations: 50
  target_score: 0.85
```

--------------------------------

### Run the File Processor Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/TUTORIAL.md

Execute the file processor agent example, which utilizes a custom skill and generates a multi-file project.

```bash
./run_general.sh 02_file_processor
```

--------------------------------

### Run the TODO List Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/TUTORIAL.md

Execute the simplest agent example to generate a TODO list application. Ensure you are in the LoongFlow directory, have activated your virtual environment, and set the necessary API keys.

```bash
cd LoongFlow
source .venv/bin/activate
export ANTHROPIC_API_KEY="your-key-here"
export ANTHROPIC_BASE_URL="your-base-url-here"

# Run the simplest example
./run_general.sh 01_todo_list
```

--------------------------------

### Start Visualization Server

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/agents/general_evolve.md

Execute this command in the project root directory to start the visualization server. It requires a port number and the path to the checkpoints directory.

```bash
# Execute in the project root directory
python agents/general_evolve/visualizer/visualizer.py \
  --port 8888 \
  --checkpoint-path output/database/checkpoints
```

--------------------------------

### Check uv Installation

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/build_agent/get_started.md

Confirm that `uv` is installed, as it is recommended for faster dependency management.

```bash
uv --version  # Confirm uv is installed
```

--------------------------------

### Install Task-Specific Dependencies

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/agents/general_evolve.md

Installs dependencies required for a specific task using uv pip. Run this command before starting a task.

```bash
# Install task-specific dependencies
uv pip install -r ./agents/general_evolve/examples/your_task_name/requirements.txt
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/README.md

Use uv to synchronize and install project dependencies. Ensure you are in the project root directory.

```bash
uv sync
```

--------------------------------

### Run Uncertainty Inequality Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/examples/uncertainty_inequality/README.md

Execute the math agent to start the evolution process for the uncertainty inequality problem. Ensure the PYTHONPATH is set correctly.

```bash
python agents/math_agent/math_agent_agent.py \
  --config agents/math_agent/examples/uncertainty_inequality/task_config.yaml \
  --initial-file agents/math_agent/examples/uncertainty_inequality/initial_program.py \
  --eval-file agents/math_agent/examples/uncertainty_inequality/eval_program.py \
  --log-level INFO
```

--------------------------------

### Run Machine Learning Agent Example

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/index.md

Initializes and runs the 'ml_example' for the Machine Learning Agent in the background. Task logs are available at './agents/ml_evolve/examples/ml_example/agent.log'.

```bash
./run_ml.sh init
./run_ml.sh run ml_example --background
```

```bash
tail -f ./agents/ml_evolve/examples/ml_example/agent.log
```

--------------------------------

### Run Task and Start Visualizer (Troubleshooting)

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/visualizer/README.md

Ensure a task has been run and has at least one iteration before starting the visualizer. This addresses the 'No tasks shown' issue.

```bash
# Run an example task first
./run_general.sh 01_todo_list

# Then start visualizer
python agents/general_agent/visualizer/visualizer.py \
    --workspace ./output-todo-list
```

--------------------------------

### Run File Processor Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/examples/02_file_processor/README.md

Navigate to the LoongFlow root directory and execute the file processor example script. The generated code will be found in the output directory.

```bash
# 1. Navigate to LoongFlow root
cd /path/to/LoongFlow

# 2. Run the example
./run_general.sh 02_file_processor

# 3. Find your generated code
cd output-file-processor/task_*/iteration_*/executor/work_dir/

# 4. Test with sample data
python main.py ../../../../../../agents/general_agent/examples/02_file_processor/sample_data/sales_data.csv
```

--------------------------------

### Create and Run ReActAgent

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/build_agent/get_started.md

Example of creating a ReActAgent with a toolkit and system prompt, then running it with a message.

```python
from loongflow.framework.react import AgentContext, ReActAgent
from loongflow.agentsdk.tools import Toolkit

# Build agent context
toolkit = Toolkit()
# Register tools...

# Create default ReAct agent
agent = ReActAgent.create_default(
    model=model, 
    sys_prompt=sys_prompt, 
    toolkit=toolkit
)

# Run the agent
result = await agent(message)
```

--------------------------------

### Run General Evolutionary Agent Example

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/index.md

Executes the 'packing_circle_in_unit_square' task for the General Evolutionary Agent. Installs necessary requirements and runs the task in the background. View logs using 'tail -f'.

```bash
uv pip install -r ./agents/general_evolve/examples/packing_circle_in_unit_square/requirements.txt
./run_task.sh packing_circle_in_unit_square --background
```

```bash
tail -f ./agents/general_evolve/examples/packing_circle_in_unit_square/run.log
```

--------------------------------

### Install LoongFlow Dependencies

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/build_agent/get_started.md

Install LoongFlow and its dependencies in the activated virtual environment using `uv`.

```bash
uv pip install -e .
```

--------------------------------

### Create Custom Task Directory

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/TUTORIAL.md

Navigate to the examples directory and create a new directory for your custom task.

```bash
cd LoongFlow/agents/general_agent/examples
mkdir my_custom_task
cd my_custom_task
```

--------------------------------

### Run LoongFlow Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/examples/README.md

Command to run a LoongFlow example using the math_agent_agent.py script. Specify configuration, initial code, and evaluation files.

```bash
# Assuming you are in the evolux project root directory
export PYTHONPATH=$PYTHONPATH:.

python agents/math_agent/math_agent_agent.py \
    --config agents/math_agent/examples/max_to_min_ratios/task_config.yaml \
    --initial-file agents/math_agent/examples/max_to_min_ratios/initial_program.py \
    --eval-file agents/math_agent/examples/max_to_min_ratios/eval_program.py
```

--------------------------------

### ML Evolve Agent Task Configuration Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/ml_agent/README.md

Example configuration for the ML Evolve Agent, including LLM and component settings.

```yaml
workspace_path: "./output"

# LLM Configuration (required)
llm_config:
  url: "http://your-llm-api/v1"
  api_key: "your-api-key"
  model: "openai/gemini-3-flash-preview"
  temperature: 0.8
  context_length: 128000
  max_tokens: 32768
  top_p: 1.0

# Component Configurations
planners:
  ml_planner:
    react_max_steps: 10
    evo_coder_timeout: 3600

executors:
  ml_executor:
    react_max_steps: 10
    evo_coder_timeout: 86400

summarizers:
  ml_summary:
    react_max_steps: 10

# Evolution Configuration
evolve:
  planner_name: "ml_planner"
  executor_name: "ml_executor"
  summary_name: "ml_summary"
  max_iterations: 100
  target_score: 1.0
  concurrency: 1

  evaluator:
    timeout: 1800

  database:
    storage_type: "in_memory"
    num_islands: 3
    population_size: 30
    checkpoint_interval: 5
    sampling_weight_power: 1.0
```

--------------------------------

### Start Visualization Dashboard

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/build_agent/general_evolve.md

Navigate to the visualizer directory and run the visualizer.py script, specifying the port and checkpoint path.

```bash
cd agents/general_evolve/visualizer
python visualizer.py --port 8888 --checkpoint-path output/database/checkpoints
```

--------------------------------

### Run Circle Packing Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/examples/04_circle_packing/README.md

Execute the circle packing optimization example using the provided shell script. This command initiates the optimization process, which may take a significant amount of time.

```bash
# 1. Navigate to LoongFlow root
cd /path/to/LoongFlow

# 2. Run the example (this will take longer!)
./run_general.sh 04_circle_packing

# 3. Monitor progress (in another terminal)
tail -f agents/general_agent/examples/04_circle_packing/run.log

# 4. Check generated solutions
cd output-circle-packing/task_*/iteration_*/executor/work_dir/
python -c "from run_packing import run_packing; c, r, s = run_packing(5); print(f'Sum of radii: {s}')"
```

--------------------------------

### Run Packing Circles Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/examples/packing_circle_in_rectangle/README.md

Execute the evolution process for the packing circles problem. Ensure your PYTHONPATH is set correctly to include the project root.

```bash
python agents/math_agent/math_agent_agent.py \
  --config agents/math_agent/examples/packing_circle_in_rectangle/task_config.yaml \
  --initial-file agents/math_agent/examples/packing_circle_in_rectangle/initial_program.py \
  --eval-file agents/math_agent/examples/packing_circle_in_rectangle/eval_program.py \
  --log-level INFO
```

--------------------------------

### Install Kaggle API Credentials

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/ml_agent/README.md

Configure Kaggle API credentials by downloading and placing the kaggle.json file in the correct directory.

```bash
# Download kaggle.json from https://www.kaggle.com/settings/account
mkdir -p ~/.kaggle && mv kaggle.json ~/.kaggle/ && chmod 600 ~/.kaggle/kaggle.json
```

--------------------------------

### Configure and Run EvolveAgent

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/build_agent/get_started.md

Example of configuring an EvolveAgent, registering worker components, and running the agent.

```python
from loongflow.framework.evolve import EvolveAgent

# Configure Evolve Agent
agent = EvolveAgent(
    config=config,
    checkpoint_path=checkpoint_path,
)

# Register worker components
agent.register_planner_worker("planner", PlanAgent)
agent.register_executor_worker("executor", ExecuteAgent)
agent.register_summary_worker("summary", SummaryAgent)

# Run the agent
result = await agent()
```

--------------------------------

### Basic Model Call Example

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/components/models/index.md

Demonstrates a basic usage scenario: creating a LiteLLMModel instance, preparing messages, and constructing a CompletionRequest.

```python
from loongflow.agentsdk.models import LiteLLMModel
from loongflow.agentsdk.message import Message
from loongflow.agentsdk.message import ContentElement
from loongflow.agentsdk.models.llm_request import CompletionRequest

# Create model instance
model = LiteLLMModel.from_config({
    "model": "gpt-4",
    "url": "https://api.openai.com/v1", 
    "api_key": "your-api-key"
})

# Prepare messages
messages = [
    Message(
        role="user",
        content=[ContentElement(mime_type="text/plain", data="Please explain Artificial Intelligence")]
    )
]

# Create request
request = CompletionRequest(messages=messages)
```

--------------------------------

### Start the Visualizer for a Single Task

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/visualizer/README.md

Launch the visualizer to monitor a specific task's output. Specify the output directory and the port to use.

```bash
python agents/general_agent/visualizer/visualizer.py \
    --port 8080 \
    --workspace ./output-todo-list
```

--------------------------------

### Run Slow Turn Puzzles Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/examples/slow_turn_puzzles/README.md

Execute the evolution process for the Slow Turn Puzzles example using the math agent. Ensure the PYTHONPATH is set correctly.

```bash
python agents/math_agent/math_agent_agent.py \
  --config agents/math_agent/examples/slow_turn_puzzles/task_config.yaml \
  --initial-file agents/math_agent/examples/slow_turn_puzzles/initial_program.py \
  --eval-file agents/math_agent/examples/slow_turn_puzzles/eval_program.py \
  --log-level INFO
```

--------------------------------

### ML Evolve Agent Evaluation Program Example

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/agents/ml_evolve.md

Provides a Python example for the `eval_program.py` script, demonstrating how to implement the evaluation interface for machine learning tasks.

```python
def evaluate(task_data_path, best_code_path, artifacts):
    """
    Evaluation function, returns a dictionary containing score and status info.
    
    Args:
        task_data_path: Path to the task data directory
        best_code_path: Path to the best code file
        artifacts: Evaluation process parameters
        
    Returns:
        dict: Contains status, score, metrics, etc.
    """
    try:
        # Execute the solution and evaluate
        result = run_machine_learning_evaluation(best_code_path)
        return {
            "status": "success",
            "score": result["score"],  # 0.0-1.0
            "metrics": {
                "accuracy": result["accuracy"],
                "f1_score": result["f1"]
            },
            "artifacts": {
                "reasoning": "Detailed evaluation result",
                "predictions": result["predictions"]
            }
        }
    except Exception as e:
        return {
            "status": "execution_failed",
            "score": 0.0,
            "summary": f"Evaluation failed: {str(e)}"
        }
```

--------------------------------

### LLM Configuration Example

Source: https://github.com/baidu-baige/loongflow/blob/main/CLAUDE.md

Example YAML configuration for LLM settings, including API URL, key, and model selection. Ensure compatibility with OpenAI standards.

```yaml
llm_config:
  url: "https://xxxxxx/v1"
  api_key: "******"
  model: "openai/gemini-3-pro-preview" # or other OpenAI-compatible models
```

--------------------------------

### Start Loongflow Visualizer

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/visualizer/README.md

Run the Loongflow visualizer in the background for a specific task and open it in the browser. Ensure the workspace directory exists.

```bash
./run_general.sh 01_todo_list --background
python agents/general_agent/visualizer/visualizer.py --workspace ./output-todo-list
open http://localhost:8080
```

--------------------------------

### Directory Structure Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/examples/README.md

Illustrates a typical directory layout for a Loongflow task, including initial program, evaluation script, and configuration files.

```text
examples/
├── max_to_min_ratios/              # Task directory
│   ├── initial_program.py          # Contains # EVOLVE-BLOCK
│   ├── eval_program.py             # Contains evaluate() function
│   ├── task_config.yaml            # Contains task prompt and parameters
│   └── README.md (Optional)        # Specific instructions for this task
└── ... other tasks

```

--------------------------------

### Launch Real-time Evolution Tracking Dashboard

Source: https://github.com/baidu-baige/loongflow/blob/main/CLAUDE.md

Start the visualizer for real-time evolution tracking of the math agent. Specify the port and checkpoint path.

```bash
python agents/math_agent/visualizer/visualizer.py --port 8888 --checkpoint-path output-circle-packing/database/checkpoints
```

--------------------------------

### LLM Configuration Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/examples/01_todo_list/README.md

Configure the Large Language Model API key and endpoint in the task_config.yaml file.

```yaml
llm_config:
  api_key: "your-key"
  url: "your-endpoint"
```

--------------------------------

### Run MLE-Bench Competition in Background

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/ml_agent/README.md

Start the evolution process for an MLE-Bench competition in the background.

```bash
# Run evolution
./run_mlebench.sh run detecting-insults-in-social-commentary --background
```

--------------------------------

### Run Task and Monitor with Visualizer

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/visualizer/README.md

Execute a task in the background and then start the visualizer to monitor its progress. This is a common workflow for development.

```bash
# Terminal 1: Run task
./run_general.sh 02_file_processor --background

# Terminal 2: Monitor with visualizer
python agents/general_agent/visualizer/visualizer.py \
    --workspace ./output-file-processor
```

--------------------------------

### Built-in Tools Configuration

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Example YAML configuration specifying the list of available built-in tools for the agent.

```yaml
build_in_tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash", "Skill", "Task"]
```

--------------------------------

### Task Configuration File Structure

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/agents/general_evolve.md

Example YAML structure for configuring tasks, including workspace, LLM, component, and evolution process settings.

```yaml
# Global directory configuration
workspace_path: "./output"

# LLM Configuration (supports OpenAI, Gemini, DeepSeek, etc.)
llm_config:
  url: "https://your-llm-api/v1"
  api_key: "your-api-key"
  model: "openai/gemini-3-pro-preview"
  temperature: 0.8
  context_length: 128000
  max_tokens: 32768

# Component Configuration (Planner, Executor, Summarizer)
planners:
  evolve_planner:
    react_max_steps: 10

executors:
  evolve_executor_fuse:
    max_rounds: 3
    react_max_steps: 15
    score_threshold: 0.95

summarizers:
  evolve_summary:
    react_max_steps: 6

# Evolution Process Configuration
evolve:
  task: "Your task description..."
  planner_name: "evolve_planner"
  executor_name: "evolve_executor_fuse"
  summary_name: "evolve_summary"
  max_iterations: 200
  target_score: 1.0
  concurrency: 3
  
  # Evaluator Configuration
  evaluator:
    timeout: 1200
    
  # Database Configuration
  database:
    storage_type: "in_memory"
    num_islands: 3
    population_size: 90
    checkpoint_interval: 1
```

--------------------------------

### Run ML Evolve Agent Task

Source: https://github.com/baidu-baige/loongflow/blob/main/AGENTS.md

Initializes and runs an ML Evolve agent task. Logs are saved in the example directory.

```bash
./run_ml.sh init
./run_ml.sh run <task_name> --background
```

--------------------------------

### ToolContext Authentication Setup

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/components/tools/index.md

Demonstrates how to configure and set authentication credentials within a `ToolContext` using `AuthConfig` and `AuthCredential`. This context can then be used during tool execution.

```python
from loongflow.agentsdk.tools.tool_context import ToolContext, AuthConfig, AuthCredential, AuthType

# Create authentication configuration
auth_config = AuthConfig(scheme=AuthType.API_KEY, key="openai_api")

# Create authentication credential
credential = AuthCredential(auth_type=AuthType.API_KEY, api_key="sk-...")

# Set authentication in tool context
context = ToolContext(function_call_id="call_123")
context.set_auth(auth_config, credential)

# Use authentication context during tool execution
response = await tool.arun(args={}, tool_context=context)
```

--------------------------------

### Run Multiple Tasks and Monitor

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/visualizer/README.md

Start multiple tasks in the background and then launch the visualizer to monitor them concurrently. This allows for easy comparison of different agent runs.

```bash
./run_general.sh 01_todo_list --background
./run_general.sh 02_file_processor --background

python agents/general_agent/visualizer/visualizer.py \
    --workspaces "output-todo-list,output-file-processor"
```

--------------------------------

### Run General Agent: To-Do List App

Source: https://github.com/baidu-baige/loongflow/blob/main/README.md

Executes the beginner example for a To-Do list application agent. This task is expected to take 5-10 minutes.

```bash
./run_general.sh 01_todo_list
```

--------------------------------

### Run General Evolve Agent Task

Source: https://github.com/baidu-baige/loongflow/blob/main/AGENTS.md

Installs task-specific dependencies and runs a General Evolve agent task. Logs are saved in the example directory.

```bash
# Install task-specific deps first
uv pip install -r ./agents/math_agent/examples/<task_name>/requirements.txt
# Run task
./run_math.sh <task_name> --background
```

--------------------------------

### Install LoongFlow with uv

Source: https://github.com/baidu-baige/loongflow/blob/main/README.md

Installs LoongFlow using uv, a fast Python package installer and resolver. Requires Python 3.12 or higher.

```bash
cd LoongFlow
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e .
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/agents/ml_evolve.md

Use this command to ensure correct dependencies are installed for the project. It requires Python 3.12 or newer.

```bash
# Ensure correct Python version
python --version  # Should be 3.12+

# Reinstall dependencies
uv sync
```

--------------------------------

### Display Help Information

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/visualizer/README.md

View all available command-line options and their descriptions for the visualizer script.

```bash
python agents/general_agent/visualizer/visualizer.py --help
```

--------------------------------

### Verify LoongFlow Installation

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/overview/quickstart.md

Test if the loongflow library can be imported and run basic pytest tests to confirm a successful installation.

```bash
# Test framework import
python -c "import loongflow; print('Installation successful!')"

# Run basic tests
uv run pytest tests/ -v
```

--------------------------------

### Install LoongFlow with conda

Source: https://github.com/baidu-baige/loongflow/blob/main/README.md

Installs LoongFlow using conda, a package and environment manager. Requires Python 3.12 or higher.

```bash
cd LoongFlow
conda create -n loongflow python=3.12
conda activate loongflow
pip install -e .
```

--------------------------------

### Start Task in Background

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/agents/general_evolve.md

Starts a task in the background using the run_task.sh script. Replace 'your_task_name' with the actual task name.

```bash
# Start the task (run in background)
./run_task.sh packing_circle_in_unit_square --background
```

--------------------------------

### Initialize MLE-Bench and Configure Kaggle API

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/agents/ml_evolve.md

Initializes the MLE-Bench environment and sets up the Kaggle API credentials for data downloads.

```bash
# Initialize MLE-Bench environment
./run_mlebench.sh init

# Configure Kaggle API (for data download)
# Download kaggle.json from https://www.kaggle.com/settings/account
mkdir -p ~/.kaggle && mv kaggle.json ~/.kaggle/ && chmod 600 ~/.kaggle/kaggle.json
```

--------------------------------

### Retrieve and Sample Solutions

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/components/memory/evolution.md

Demonstrates methods for retrieving the best solutions, sampling solutions for evolutionary operations, and checking the memory status.

```python
# Get best solutions
best_solutions = memory.get_best_solutions(island_id=0, top_k=5)

# Sample solutions for crossover/mutation
parent = memory.sample(island_id=0, exploration_rate=0.1)

# View memory status
status = memory.memory_status()
```

--------------------------------

### Evaluator Code Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/examples/README.md

Example of an evaluator function for LoongFlow. It runs generated code, verifies results, and returns a score and status.

```python
def evaluate(program_path):
    try:
        # 1. Run the generated code
        result = run_external_function(program_path, "optimize_construct", timeout_seconds=20)

        # 2. Verify results
        if not is_valid(result):
            return {
                "status": "validation_failed",
                "score": 0.0,
                "summary": "Output shape mismatch."
            }

        # 3. Calculate score (assuming the goal is to maximize some ratio)
        score = calculate_score(result)

        return {
            "status": "success",
            "score": score,
            "summary": f"Success! Score: {score}",
            "metrics": {"raw_value": result}
        }

    except Exception as e:
        return {
            "status": "execution_failed",
            "score": 0.0,
            "summary": str(e)
        }
```

--------------------------------

### Instantiate LiteLLMModel from Configuration

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/components/models/index.md

Demonstrates creating a LiteLLMModel instance using a configuration dictionary, specifying model details and API credentials.

```python
from loongflow.agentsdk.models import LiteLLMModel

# Create model instance from config
model = LiteLLMModel.from_config({
    "model": "gpt-4",
    "url": "https://api.openai.com/v1",
    "api_key": "your-api-key",
    "timeout": 600,  # Optional
    "model_provider": "openai"  # Optional
})
```

--------------------------------

### Custom Skill Description (SKILL.md) Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Example content for a SKILL.md file, defining the skill's name, description, features, and usage.

```markdown
---
name: "my_skill"
description: "Processing data files skill. Used for data cleaning, transformation, and analysis."
---

# My Skill

## Features
- Data file reading and parsing
- Data cleaning and preprocessing
- Common data transformation operations

## Usage
Use built-in file_io tools to read data files, then perform corresponding processing.
```

--------------------------------

### Create a Custom Skill Directory

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/TUTORIAL.md

Set up the directory structure for a new custom skill named 'my-skill'.

```bash
# Create skill directory
mkdir -p .claude/skills/my-skill
```

--------------------------------

### Run General Agent: Circle Packing Optimization (Background)

Source: https://github.com/baidu-baige/loongflow/blob/main/README.md

Executes the expert example for circle packing optimization as a background task. This task is expected to take 20-30 minutes. Use 'tail -f' to check logs.

```bash
./run_general.sh 04_circle_packing --background
```

--------------------------------

### Start Visualizer for Single Workspace

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Starts the visualization dashboard for a single specified workspace. This allows for real-time monitoring of a specific task's progress.

```bash
python agents/general_agent/visualizer/visualizer.py --workspace ./output-todo-list
```

--------------------------------

### Running the Math Agent Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/examples/sums_and_differences_problems_1/README.md

Execute the LoongFlow math agent to evolve a Python algorithm for sums and differences problems. Ensure your PYTHONPATH is set correctly.

```bash
python agents/math_agent/math_agent_agent.py \
  --config agents/math_agent/examples/sums_and_differences_problems_1/task_config.yaml \
  --initial-file agents/math_agent/examples/sums_and_differences_problems_1/initial_program.py \
  --eval-file agents/math_agent/examples/sums_and_differences_problems_1/eval_program.py \
  --log-level INFO
```

--------------------------------

### Initialize and Run ReActAgent

Source: https://github.com/baidu-baige/loongflow/blob/main/README.md

Shows how to set up a ReActAgent with a custom toolkit, including registering tools like TodoReadTool and TodoWriteTool. The agent is then run with a message.

```python
from loongflow.framework.react import AgentContext, ReActAgent
from loongflow.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)
```

--------------------------------

### Read OWASP Top 10 Guide

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/TUTORIAL.md

Access the OWASP Top 10 guide for Python from the code-analysis skill's references to learn about common web security risks.

```bash
# Read OWASP Top 10 guide
cat .claude/skills/code-analysis/references/owasp_top10_python.md | less
```

--------------------------------

### Example LoongFlow Configuration File

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/README.md

A sample YAML configuration file defining workspace, LLM, component, and evolutionary process parameters. Customize LLM API details and evolutionary settings as needed.

```yaml
# Global directory configuration
workspace_path: "./output"

# LLM Configuration
llm_config:
  url: "http://your-llm-api/v1"
  api_key: "your-api-key"
  model: "deepseek-r1-250528"
  # ... other parameters

# Component Configuration (Planner, Executor, Summarizer)
planners:
  evolve_planner: { ... }
executors:
  evolve_executor_fuse: { ... }
summarizers:
  evolve_summary: { ... }

# Evolutionary Process Configuration
evolve:
  task: "Find n points in d-dimensional space..."
  planner_name: "evolve_planner"
  executor_name: "evolve_executor_fuse"
  summary_name: "evolve_summary"
  max_iterations: 1000
  target_score: 1.0

  # Evaluator Configuration
  evaluator:
    timeout: 1200

  # Database/Population Configuration
  database:
    storage_type: "in_memory"
    population_size: 100

```

--------------------------------

### Stop Background Task

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Command to stop a background task for a specific example.

```bash
./run_general.sh stop 01_todo_list
```

--------------------------------

### Manage Tools with Toolkit

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/components/tools/index.md

Shows how to create a Toolkit, register built-in tools like ReadTool and WriteTool, retrieve tool declarations, and execute tools synchronously or asynchronously.

```python
from loongflow.agentsdk.tools import Toolkit, ReadTool, WriteTool

# Create toolkit
toolkit = Toolkit()

# Register tools (supports authentication configuration)
toolkit.register_tool(ReadTool())
toolkit.register_tool(WriteTool())

# Get tool declarations (returns OpenAI function call format)
declarations = toolkit.get_declarations()

# Synchronous tool execution
response = toolkit.run("Read", args={"file_path": "/path/to/file"})

# Asynchronous tool execution
response = await toolkit.arun("Read", args={"file_path": "/path/to/file"})
```

--------------------------------

### Start Visualization Service

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/README.md

Launch the LoongFlow visualization service to monitor evolutionary process metrics. Requires navigating to the 'visualizer' directory and specifying the port and checkpoint path.

```bash
cd visualizer
python visualizer.py --port 8888 --checkpoint-path output/database/checkpoints
```

--------------------------------

### Reference Custom Skill in Configuration

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Example of how to include a custom skill in the planner's configuration.

```yaml
planners:
  general_planner:
    skills: ["my_skill"]
```

--------------------------------

### Create Virtual Environment with conda

Source: https://github.com/baidu-baige/loongflow/blob/main/CLAUDE.md

Alternatively, use conda to create a virtual environment and install dependencies.

```bash
conda create -n loongflow python=3.12
conda activate loongflow
pip install -e .
```

--------------------------------

### Instantiate LiteLLMModel Directly

Source: https://github.com/baidu-baige/loongflow/blob/main/docs/en/components/models/index.md

Shows how to directly instantiate a LiteLLMModel by providing model parameters and API credentials as arguments.

```python
from loongflow.agentsdk.models import LiteLLMModel

# Or instantiate directly
model = LiteLLMModel(
    model_name="gpt-4",
    base_url="https://api.openai.com/v1",
    api_key="your-api-key",
    timeout=600,  # Optional
    model_provider="openai"  # Optional
)
```

--------------------------------

### Run Custom ML Task in Background

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/ml_agent/README.md

Start the evolution process for a custom ML task in the background.

```bash
# Run evolution (ml_example is a demo with Iris classification)
./run_ml.sh run ml_example --background
```

--------------------------------

### Run Packing Hexagons Example

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/math_agent/examples/packing_hexagons_in_hexagons/README.md

Execute the LoongFlow agent to evolve a solution for packing hexagons. Ensure your PYTHONPATH is set correctly to include the project root.

```bash
python agents/math_agent/math_agent_agent.py \
  --config agents/math_agent/examples/packing_hexagons_in_hexagons/task_config.yaml \
  --initial-file agents/math_agent/examples/packing_hexagons_in_hexagons/initial_program.py \
  --eval-file agents/math_agent/examples/packing_hexagons_in_hexagons/eval_program.py \
  --log-level INFO
```

--------------------------------

### Load Skills in Planner Configuration

Source: https://github.com/baidu-baige/loongflow/blob/main/agents/general_agent/README.md

Example of how to specify skills for the general planner in the project's configuration file. Ensure skill names match folder names under .claude/skills/.

```yaml
planners:
  general_planner:
    skills: ["skill-creator", "your-skill-name"]  # Skill names correspond to folder names under .claude/skills/
```

--------------------------------

### Task Configuration Example

Source: https://github.com/baidu-baige/loongflow/blob/main/src/loongflow/framework/pes/README.md

Defines the global LLM settings, evolution process parameters, database and island model configurations, and evaluator settings for a custom task.

```yaml
# 1. Global LLM Configuration
llm_config:
  model: "deepseek-r1-250528"
  url: "http://your-api-endpoint/v1"
  api_key: "your-api-key"
  temperature: 0.8
  max_tokens: 32768

# 2. Evolution Process Configuration
evolve:
  task: "Find the optimal configuration for..."  # Your task description
  target_score: 1.0                              # Stop when this score is reached
  max_iterations: 100                            # Maximum number of evolution loops
  concurrency: 5                                 # Number of concurrent workers (parallel evolution)

  # Database & Population Settings (Island Model)
  database:
    storage_type: "in_memory"      # or "redis"
    num_islands: 3                 # Number of parallel populations
    population_size: 100           # Solutions per island
    migration_interval: 10         # Exchange solutions every N iterations
    checkpoint_interval: 50        # Auto-save checkpoint every N iterations

  # Component Selection
  planner_name: "evolve_planner"
  executor_name: "evolve_executor_fuse"
  summary_name: "evolve_summary"

  # Evaluator Settings
  evaluator:
    timeout: 60            # Seconds allowed for evaluation
    evaluate_code: |
      from eval_program import evaluate
```