🤖 Experiment on Agent (ExpAgent) 🤖

A framework to experiment on agent easily, quickly, and locally for learning purpose

• Accumulate experience with popular agents for fresh researchers
• User-friendly usage without complicated engineering implementation
• Call LLMs locally or through API key
• Actions/Tools/Skills can be unifiedly loaded and used locally
• Easily implement the planner, e.g., ReAct and ReAcTree

If you find this project useful, please consider giving it a star! ⭐

📑 Content

• 🚀 To Do List
• 🏗️ Architecture
• 🚅 Quick Start
• 🛠️ More Usage
• 📋 Supported Acts
• 🎯 Supported Planner
• Citation
• Acknowledgments & References

🚀 To Do List

• Basic operation update_plan needs to be designed
• Dynamic acts need to be designed and implemented
• Envolution module and experience mechanism
• More tools need to keep being developed, like AI_memory, browser
• More skills need to be tested
• ReAcTree planner needs more samples to test fallback and parallel

🏗️ Architecture

The project is organized into several key modules:

Agent Model (agent_model/)

• Core agent implementation with support for both local models and API-based models
• Basic operations like act, select, reasoning, plan, etc. are implemented
• Built-in RAG (Retrieval Augmented Generation) functionality
• Verifier module for validating agent responses
• Support for multiple LLM providers (DeepSeek, AliCloud, etc.)

Act Module: Actions/Tools/Skills (act/)

• Unified interface for different types of agent capabilities, which is called act
• Actions: High-level operations like answer, which only process the text for different purposes
• Tools: Utility functions like calculator, file operations, shell commands, web search
• Skills: Specialized AI capabilities defined in markdown files with instructions

Planners (planner/)

• ReAct: Implements the Reasoning and Acting framework with thought-action-observation cycles
• ReAcTree: Advanced tree-based planner supporting sequence, fallback, and parallel execution modes
• DAG-ReAct: Decompose a question into a DAG (Reasoning) and traverse the graph (Acting)
• Configurable parameters for controlling agent behavior and execution limits

🚅 Quick Start

Step 1: Install the required packages

pip install -r requirements.txt

Step 2-1: Create api_keys.json, if you would like to call LLM via API, like:

{
  "DEEPSEEK_API_KEY": "xxx",
  "DASHSCOPE_API_KEY": "xxx",
  "HF_ENDPOINT": "xxx",
  "HF_TOKEN": "xxx"
}

Use agent_model.api_models.openai.OpenAIModel to set your base_url, model_name, api_key. For DeepSeek, you can directely use agent_model.api_models.deepseek.DeepSeekModel. DashScope is used for the text-embedding model in RAG

Step 2-2: If you would like to call local LLMs：

Option 1: the MNN (Mobile Neural Network) framework is adopted for deployment. You should download the MNN model from modelscope and put it in the ./models folder, like ./models/Qwen3-4B-MNN. To obtain better performance, the relatively large models (>7B) are recommended

Option 2: Start a local server through your deployment framework (e.g., vllm, sglang, llama.cpp), then call the server through OpenAIModel, the default base_rul is http://localhost:8080/v1/

Step 3: Edit agent_interface.py to pass your model (Default: DeepSeekModel)

config_path = "./models/Qwen3-4B-MNN/" # Initialize the local model (MNN)
# model = OpenAIModel() # Initialize the openai-compatible model
model = DeepSeekModel(enable_think=False) # Initialize the DeepSeek API model
agent = AgentModel(config_path, model=model, ...) # if model is passed, the config_path is ignored

Step 4: Run the run_query.py to see the result

python run_query.py

Step 5: Run the run_gaia.py to evaluate your agent on GAIA

python run_gaia.py

Please pay attention to the balance in your account and the tools required by GAIA. Evaluation on GAIA may require a significant amount of time and expense, and some tools may need to be implemented by yourself (e.g., Video parsing)

🛠️ More Usage

The agent_interface.py shows how to initialize a entire agent in ExpAgent:

1. Acts Initialization

from act import *

# Prepare action and tool dictionaries
action_dict = {}
action_dict.update({
    "answer": Answer,
})

tool_dict = {}
tool_dict.update({
    "shell": Shell,
    "calculator": Calculator,
    "view_text_file": ViewTextFile,
    "write_text_file": WriteTextFile,
})

2. Agent Model Initialization

You can define config_path to call local MNN LLMs. If an API-based model is passed into Agent Model, the config_path is ignored. In addition, you can check how to add an API-based model by DeepSeekModel, which is very easy.

from agent_model import AgentModel
from agent_model.api_models.deepseek import DeepSeekModel

# Initialize the local model
config_path = "./models/Qwen3-8B-MNN/"
# Initialize the API model
model = DeepSeekModel(enable_think=False)
# rag is used for search tool. If don't need this tool, set False.
# If you register the search tool, RAG will be automatically registered.
agent = AgentModel(config_path,
                model=model,
                action_dict=action_dict,
                tool_dict=tool_dict,
                use_skills=False,
                use_rag=rag, 
                planner_cfg=None,
                planner_cls=None
                )

Note that planner_cfg and planner_cls here are reserved for perform_skill and perform_browser, which need create a new agent to conduct a skill or browser.

3. Planner initialization

The Verifier is exploited to determine whether current query is completed. Only config_path or model need to be passed for Verifier.

The Config is used to set some basic parameters for the planner. For example, Config of ReAcTreePlanner contains:

• max_steps: the total number of the tree nodes
• max_decisions: the maximum decision times for a node
• max_depth: the depth of the tree
• max_think: the maximum Think times for a node
• max_plan: the maximum Plan times for a node

from agent_model import Verifier
from planner.ReAcTree import Config, ReAcTreePlanner

verifier = Verifier(
  # cfg_path=config_path,
  model=agent.model
)
cfg = Config()
planner = ReAcTreePlanner(
  cfg=cfg,
  agent=agent,
  verifier=verifier
)

4. Invoke planner.collect to start the Agent and get the whole trajectory by terminate_info['response']. If you only want the final answer for the query, set extract_answer=True. This will call LLM to extract the final answer from the trajectory as the return.

terminate_info = planner.collect(query, extract_answer=False)
if extract_answer:
    return terminate_info
return terminate_info['response']

📋 Supported Acts

Actions

• Answer: Respond the question/answer the query/improve the response

Tools

• Calculator: Safe evaluation of mathematical expressions and perform calculation
• File Operations: Read/write/edit text files with range support
• Shell Commands: Execute system commands safely
• Wikipedia Search: Wikipedia search capabilities
• Baidu Search: Baidu search capabilities
• Web Search: Web search capabilities via specific URL
• List Directory Contents: List files and directories in a specified path
• Grep: Search for patterns in files using regex with optional glob filtering
• Glob: Find files matching glob patterns (e.g., ".py", "**/.js")
• Read Many Files: Read content of multiple text files or files matching glob patterns

Skills

• PDF: Process pdf files
• Skill Creator: Create skills by LLM (Not tested)

🎯 Supported Planner

• ReAct: Traditional reasoning-acting loop for step-by-step problem solving. This is implemented by vibe-coding and may be not that perfect.
• ReAcTree: The original paper of ReAcTree is designed for Long-Horizon Task Planning. ExpAgent transfers it to general daily tasks, and provides visualization of agent's decision flow. ReAcTree is a hierarchical tree-based planning method with three control flows:
  • Sequence: Execute subtasks in order, stop on failure
  • Fallback: Try alternatives until one succeeds
  • Parallel: Execute multiple subtasks concurrently
  • Above figure and py_test.py (originally has add function) are the results of query: Write a new function that implements multiplication to py_test.py, also create test sample, then run this python file
• DAG-ReAct: First, planning by decomposing a question into a DAG; Second, execute via traversing the constructed DAG

Citation

@misc{expagent,
  title = {ExpAgent: A framework to experiment on agent easily, quickly and locally},
  author = {Caibo Feng},
  year = {2026},
}

Acknowledgments & References

Implementation and planning method are inspired by following works:

Code Implementation:

• HelloAgents
• AgentFlow
• AgentScope
• Minion
• Qwen-Code

Planning Algorithm:

• ReAcTree

Skills:

• Anthropics-skills