EvoAgentX

EvoAgentX

🚀 EvoAgentX: Building a Self-Evolving Ecosystem of AI Agents

Stars: 1305

Visit
 screenshot

EvoAgentX is an open-source framework for building, evaluating, and evolving LLM-based agents or agentic workflows in an automated, modular, and goal-driven manner. It enables developers and researchers to move beyond static prompt chaining or manual workflow orchestration by introducing a self-evolving agent ecosystem. The framework includes features such as agent workflow autoconstruction, built-in evaluation, self-evolution engine, plug-and-play compatibility, comprehensive built-in tools, memory module support, and human-in-the-loop interactions.

README:

EvoAgentX

Building a Self-Evolving Ecosystem of AI Agents

EvoAgentX Homepage Docs Discord Twitter Wechat GitHub star chart GitHub fork License

English | 简体中文

An automated framework for evaluating and evolving agentic workflows.

What is EvoAgentX

EvoAgentX is an open-source framework for building, evaluating, and evolving LLM-based agents or agentic workflows in an automated, modular, and goal-driven manner.

At its core, EvoAgentX enables developers and researchers to move beyond static prompt chaining or manual workflow orchestration. It introduces a self-evolving agent ecosystem, where AI agents can be constructed, assessed, and optimized through iterative feedback loops—much like how software is continuously tested and improved.

✨ Key Features

  • 🧱 Agent Workflow Autoconstruction

    From a single prompt, EvoAgentX builds structured, multi-agent workflows tailored to the task.

  • 🔍 Built-in Evaluation

    It integrates automatic evaluators to score agent behavior using task-specific criteria.

  • 🔁 Self-Evolution Engine

    Agents don’t just work—they learn. EvoAgentX evolves workflows using optimization strategies like retrieval augmentation, mutation, and guided search.

  • 🧩 Plug-and-Play Compatibility

    Easily integrate original OpenAI and qwen or other popular models, including Claude, Deepseek, kimi models through (LiteLLM, siliconflow or openrouter). If you want to use LLMs locally deployed on your own machine, you can try LiteLLM.

  • 🧰 Comprehensive Built-in Tools

    EvoAgentX ships with a rich set of built-in tools that empower agents to interact with real-world environments.

  • 🧠 Memory Module

    EvoAgentX supports both ephemeral (short-term) and persistent (long-term) memory systems.

  • 🧑‍💻 Human-in-the-Loop (HITL) Interactions

    EvoAgentX supports interactive workflows where humans review, correct, and guide agent behavior.

🚀 What You Can Do with EvoAgentX

EvoAgentX isn’t just a framework — it’s your launchpad for real-world AI agents.

Whether you're an AI researcher, workflow engineer, or startup team, EvoAgentX helps you go from a vague idea to a fully functional agentic system — with minimal engineering and maximum flexibility.

Here’s how:

  • 🔍 Struggling to improve your workflows?
    EvoAgentX can automatically evolve and optimize your agentic workflows using SOTA self-evolving algorithms, driven by your dataset and goals.

  • 🧑‍💻 Want to supervise the agent and stay in control?
    Insert yourself into the loop! EvoAgentX supports Human-in-the-Loop (HITL) checkpoints, so you can step in, review, or guide the workflow as needed — and step out again.

  • 🧠 Frustrated by agents that forget everything?
    EvoAgentX provides both short-term and long-term memory modules, enabling your agents to remember, reflect, and improve across interactions.

  • ⚙️ Lost in manual workflow orchestration?
    Just describe your goal — EvoAgentX will automatically assemble a multi-agent workflow that matches your intent.

  • 🌍 Want your agents to actually do things?
    With a rich library of built-in tools (search, code, browser, file I/O, APIs, and more), EvoAgentX empowers agents to interact with the real world, not just talk about it.

🧰 EvoAgentX Built-in Tools Summary

EvoAgentX ships with a comprehensive suite of built-in tools, enabling agents to interact with code environments, search engines, databases, filesystems, images, and browsers. These modular toolkits form the backbone of multi-agent workflows and are easy to extend, customize, and test.

Categories include:

  • 🧮 Code Interpreters (Python, Docker)
  • 🔍 Search & HTTP Requests (Google, Wikipedia, arXiv, RSS)
  • 🗂️ Filesystem Utilities (read/write, shell commands)
  • 🧠 Databases (MongoDB, PostgreSQL, FAISS)
  • 🖼️ Image Tools (analysis, generation)
  • 🌐 Browser Automation (low-level & LLM-driven)

We actively welcome contributions from the community!
Feel free to propose or submit new tools via pull requests or discussions.

Click to expand full table 🔽
Toolkit Name Description Code File Path Test File Path
🧰 Code Interpreters
PythonInterpreterToolkit Safely execute Python code snippets or local .py scripts with sandboxed imports and controlled filesystem access. link link
DockerInterpreterToolkit Run code (e.g., Python) inside an isolated Docker container—useful for untrusted code, special deps, or strict isolation. link link
🧰 Search & Request Tools
WikipediaSearchToolkit Search Wikipedia and retrieve results with title, summary, full content, and URL. link link
GoogleSearchToolkit Google Custom Search (official API). Requires GOOGLE_API_KEY and GOOGLE_SEARCH_ENGINE_ID. link link
GoogleFreeSearchToolkit Google-style search without API credentials (lightweight alternative). link link
DDGSSearchToolkit Search using DDGS with multiple backends and privacy-focused results link link
SerpAPIToolkit Multi-engine search via SerpAPI (Google/Bing/Baidu/Yahoo/DDG) with optional content scraping. Requires SERPAPI_KEY. link link
SerperAPIToolkit Google search via SerperAPI with content extraction. Requires SERPERAPI_KEY. link link
RequestToolkit General HTTP client (GET/POST/PUT/DELETE) with params, form, JSON, headers, raw/processed response, and optional save to file. link link
ArxivToolkit Search arXiv for research papers (title, authors, abstract, links/categories). link link
RSSToolkit Fetch RSS feeds (with optional webpage content extraction) and validate feeds. link link
🧰 FileSystem Tools
StorageToolkit File I/O utilities: save/read/append/delete, check existence, list files, list supported formats (pluggable storage backends). link link
CMDToolkit Execute shell/CLI commands with working directory and timeout control; returns stdout/stderr/return code. link link
FileToolkit File operations toolkit for managing files and directories link link
🧰 Database Tools
MongoDBToolkit MongoDB operations—execute queries/aggregations, find with filter/projection/sort, update, delete, info. link link
PostgreSQLToolkit PostgreSQL operations—generic SQL execution, targeted SELECT (find), UPDATE, CREATE, DELETE, INFO. link link
FaissToolkit Vector database (FAISS) for semantic search—insert documents (auto chunk+embed), query by similarity, delete by id/metadata, stats. link link
🧰 Image Handling Tools
ImageAnalysisToolkit Vision analysis (OpenRouter GPT-4o family): describe images, extract objects/UI info, answer questions about an image. link link
OpenAIImageGenerationToolkit Text-to-image via OpenAI (DALL·E family) with size/quality/style controls. link link
FluxImageGenerationToolkit Text-to-image via Flux Kontext Max (BFL) with aspect ratio, seed, format, prompt upsampling, and safety tolerance. link link
🧰 Browser Tools
BrowserToolkit Fine-grained browser automation: initialize, navigate, type, click, resnapshot page, read console logs, and close. link link
BrowserUseToolkit High-level, natural-language browser automation (navigate, fill forms, click, search, etc.) driven by an LLM. link link

🔥 EAX Latest News

  • [Aug 2025] 🚀 New Survey Released!
    Our team just published a comprehensive survey on Self-Evolving AI Agents—exploring how agents can learn, adapt, and optimize over time.
    👉 Read it on arXiv 👉 Check the repo

  • [July 2025] 📚 EvoAgentX Framework Paper is Live!
    We officially published the EvoAgentX framework paper on arXiv, detailing our approach to building evolving agentic workflows.
    👉 Check it out

  • [July 2025] ⭐️ 1,000 Stars Reached!
    Thanks to our amazing community, EvoAgentX has surpassed 1,000 GitHub stars!

  • [May 2025] 🚀 Official Launch!
    EvoAgentX is now live! Start building self-evolving AI workflows from day one.
    🔧 Get Started on GitHub

⚡ Get Started

Installation

We recommend installing EvoAgentX using pip:

pip install git+https://github.com/EvoAgentX/EvoAgentX.git

For local development or detailed setup (e.g., using conda), refer to the Installation Guide for EvoAgentX.

Example (optional, for local development):
git clone https://github.com/EvoAgentX/EvoAgentX.git
cd EvoAgentX
# Create a new conda environment
conda create -n evoagentx python=3.11

# Activate the environment
conda activate evoagentx

# Install the package
pip install -r requirements.txt
# OR install in development mode
pip install -e .

LLM Configuration

API Key Configuration

To use LLMs with EvoAgentX (e.g., OpenAI), you must set up your API key.

Option 1: Set API Key via Environment Variable
  • Linux/macOS:
export OPENAI_API_KEY=<your-openai-api-key>
  • Windows Command Prompt:
set OPENAI_API_KEY=<your-openai-api-key>
  • Windows PowerShell:
$env:OPENAI_API_KEY="<your-openai-api-key>" # " is required 

Once set, you can access the key in your Python code with:

import os
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
Option 2: Use .env File
  • Create a .env file in your project root and add the following:
OPENAI_API_KEY=<your-openai-api-key>

Then load it in Python:

from dotenv import load_dotenv 
import os 

load_dotenv() # Loads environment variables from .env file
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

Configure and Use the LLM

Once the API key is set, initialise the LLM with:

from evoagentx.models import OpenAILLMConfig, OpenAILLM

# Load the API key from environment
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Define LLM configuration
openai_config = OpenAILLMConfig(
    model="gpt-4o-mini",       # Specify the model name
    openai_key=OPENAI_API_KEY, # Pass the key directly
    stream=True,               # Enable streaming response
    output_response=True       # Print response to stdout
)

# Initialize the language model
llm = OpenAILLM(config=openai_config)

# Generate a response from the LLM
response = llm.generate(prompt="What is Agentic Workflow?")

📖 More details on supported models and config options: LLM module guide.

Automatic WorkFlow Generation

Once your API key and language model are configured, you can automatically generate and execute multi-agent workflows in EvoAgentX.

🧩 Core Steps:

  1. Define a natural language goal
  2. Generate the workflow with WorkFlowGenerator
  3. Instantiate agents using AgentManager
  4. Execute the workflow via WorkFlow

💡 Minimal Example:

from evoagentx.workflow import WorkFlowGenerator, WorkFlowGraph, WorkFlow
from evoagentx.agents import AgentManager

goal = "Generate html code for the Tetris game"
workflow_graph = WorkFlowGenerator(llm=llm).generate_workflow(goal)

agent_manager = AgentManager()
agent_manager.add_agents_from_workflow(workflow_graph, llm_config=openai_config)

workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)
output = workflow.execute()
print(output)

You can also:

  • 📊 Visualise the workflow: workflow_graph.display()
  • 💾 Save/load workflows: save_module() / from_file()

📂 For a complete working example, check out the workflow_demo.py

Tool-Enabled Workflows Generation:

In more advanced scenarios, your workflow agents may need to use external tools. EvoAgentX allows Automatic tool integration: Provide a list of toolkits to WorkFlowGenerator. The generator will consider these and include them in the agents if appropriate.

For instance, to enable an Arxiv toolkit:

from evoagentx.tools import ArxivToolkit

# Initialize a command-line toolkit for file operations
arxiv_toolkit = ArxivToolkit()

# Generate a workflow with the toolkit available to agents
wf_generator = WorkFlowGenerator(llm=llm, tools=[arxiv_toolkit])
workflow_graph = wf_generator.generate_workflow(goal="Find and summarize the latest research on AI in the field of finance on arXiv")

# Instantiate agents with access to the toolkit
agent_manager = AgentManager(tools=[arxiv_toolkit])
agent_manager.add_agents_from_workflow(workflow_graph, llm_config=openai_config)

workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)
output = workflow.execute()
print(output)

In this setup, the workflow generator may assign the ArxivToolkit to relevant agents, enabling them to execute shell commands as part of the workflow (e.g. creating directories and files)

Human-in-the-Loop (HITL) Support:

In advanced scenarios, EvoAgentX supports integrating human-in-the-loop interactions within your agent workflows. This means you can pause an agent’s execution for manual approval or inject user-provided input at key steps, ensuring critical decisions are vetted by a human when needed.

All human interactions are managed through a central HITLManager instance. The HITL module includes specialized agents like HITLInterceptorAgent for approval gating and HITLUserInputCollectorAgent for collecting user data.

For instance, to require human approval before an email-sending agent executes its action:

from evoagentx.hitl import HITLManager, HITLInterceptorAgent, HITLInteractionType, HITLMode

hitl_manager = HITLManager()
hitl_manager.activate()  # Enable HITL (disabled by default)

# Interceptor agent to approve/reject the DummyEmailSendAction of DataSendingAgent
interceptor = HITLInterceptorAgent(
    target_agent_name="DataSendingAgent",
    target_action_name="DummyEmailSendAction",
    interaction_type=HITLInteractionType.APPROVE_REJECT,
    mode=HITLMode.PRE_EXECUTION    # ask before action runs
)
# Map the interceptor’s output field back to the workflow’s input field for continuity
hitl_manager.hitl_input_output_mapping = {"human_verified_data": "extracted_data"}

# Add the interceptor to the AgentManager and include HITL in the workflow execution
agent_manager.add_agent(interceptor)
workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm, hitl_manager=hitl_manager)

When this interceptor triggers, the workflow will pause and prompt in the console for [a]pprove or [r]eject before continuing. If approved, the flow proceeds using the human-verified data; if rejected, the action is skipped or handled accordingly.

📂 For a complete working example, check out the tutorial /hitl.md

Demo Video

Watch on YouTube Watch on Bilibili

Your browser does not support the video tag.

In this demo, we showcase the workflow generation and execution capabilities of EvoAgentX through two examples:

  • Application 1: Intelligent Job Recommendation from Resume
  • Application 2: Visual Analysis of A-Share Stocks

✨ Final Results


Application 1:
Job Recommendation

Application 2:
Stock Visual Analysis

Evolution Algorithms

We have integrated some existing agent/workflow evolution algorithms into EvoAgentX, including TextGrad, MIPRO and AFlow.

To evaluate the performance, we use them to optimize the same agent system on three different tasks: multi-hop QA (HotPotQA), code generation (MBPP) and reasoning (MATH). We randomly sample 50 examples for validation and other 100 examples for testing.

Tip: We have integrated these benchmark and evaluation code in EvoAgentX. Please refer to the benchmark and evaluation tutorial for more details.

📊 Results

Method HotPotQA
(F1%)
MBPP
(Pass@1 %)
MATH
(Solve Rate %)
Original 63.58 69.00 66.00
TextGrad 71.02 71.00 76.00
AFlow 65.09 79.00 71.00
MIPRO 69.16 68.00 72.30

Please refer to the examples/optimization folder for more details.

Applications

We use our framework to optimize existing multi-agent systems on the GAIA benchmark. We select Open Deep Research and OWL, two representative multi-agent framework from the GAIA leaderboard that is open-source and runnable.

We apply EvoAgentX to optimize their prompts. The performance of the optimized agents on the GAIA benchmark validation set is shown in the figure below.

Open Deep Research Optimization
Open Deep Research
OWL Optimization
OWL Agent

Full Optimization Reports: Open Deep Research and OWL.

Tutorial and Use Cases

💡 New to EvoAgentX? Start with the Quickstart Guide for a step-by-step introduction.

Explore how to effectively use EvoAgentX with the following resources:

Cookbook Colab Notebook Description
Build Your First Agent Build Your First Agent Quickly create and manage agents with multi-action capabilities.
Build Your First Workflow Build Your First Workflow Learn to build collaborative workflows with multiple agents.
Working with Tools Working with Tools Master EvoAgentX's powerful tool ecosystem for agent interactions
Automatic Workflow Generation Automatic Workflow Generation Automatically generate workflows from natural language goals.
Benchmark and Evaluation Tutorial Benchmark and Evaluation Tutorial Evaluate agent performance using benchmark datasets.
TextGrad Optimizer Tutorial TextGrad Optimizer Tutorial Automatically optimise the prompts within multi-agent workflow with TextGrad.
AFlow Optimizer Tutorial AFlow Optimizer Tutorial Automatically optimise both the prompts and structure of multi-agent workflow with AFlow.
Human-In-The-Loop support Enable HITL functionalities in your WorkFlow.

🛠️ Follow the tutorials to build and optimize your EvoAgentX workflows.

🚀 We're actively working on expanding our library of use cases and optimization strategies. More coming soon — stay tuned!

🎯 Roadmap

  • [ ] Modularize Evolution Algorithms: Abstract optimization algorithms into plug-and-play modules that can be easily integrated into custom workflows.
  • [ ] Develop Task Templates and Agent Modules: Build reusable templates for typical tasks and standardized agent components to streamline application development.
  • [ ] Integrate Self-Evolving Agent Algorithms: Incorporate more recent and advanced agent self-evolution across multiple dimensions, including prompt tuning, workflow structures, and memory modules.
  • [ ] Enable Visual Workflow Editing Interface: Provide a visual interface for workflow structure display and editing to improve usability and debugging.

🙋 Support

Join the Community

📢 Stay connected and be part of the EvoAgentX journey!
🚩 Join our community to get the latest updates, share your ideas, and collaborate with AI enthusiasts worldwide.

  • Discord — Chat, discuss, and collaborate in real-time.
  • X (formerly Twitter) — Follow us for news, updates, and insights.
  • WeChat — Connect with our Chinese community.

Add the meeting to your calendar

📅 Click the link below to add the EvoAgentX Weekly Meeting (Sundays, 16:30–17:30 GMT+8) to your calendar:

👉 Add to your Google Calendar

👉 Add to your Tencent Meeting

👉 Download the EvoAgentX_Weekly_Meeting.ics file

Contact Information

If you have any questions or feedback about this project, please feel free to contact us. We highly appreciate your suggestions!

We will respond to all questions within 2-3 business days.

Community Call

🙌 Contributing to EvoAgentX

Thanks go to these awesome contributors

We appreciate your interest in contributing to our open-source initiative. We provide a document of contributing guidelines which outlines the steps for contributing to EvoAgentX. Please refer to this guide to ensure smooth collaboration and successful contributions. 🤝🚀

Star History Chart

📖 Citation

Please consider citing our work if you find EvoAgentX helpful:

📄 EvoAgentX 📄 Survey Paper

@article{wang2025evoagentx,
  title={EvoAgentX: An Automated Framework for Evolving Agentic Workflows},
  author={Wang, Yingxu and Liu, Siwei and Fang, Jinyuan and Meng, Zaiqiao},
  journal={arXiv preprint arXiv:2507.03616},
  year={2025}
}
@article{fang202survey,
      title={A Comprehensive Survey of Self-Evolving AI Agents: A New Paradigm Bridging Foundation Models and Lifelong Agentic Systems}, 
      author={Jinyuan Fang and Yanwen Peng and Xi Zhang and Yingxu Wang and Xinhao Yi and Guibin Zhang and Yi Xu and Bin Wu and Siwei Liu and Zihao Li and Zhaochun Ren and Nikos Aletras and Xi Wang and Han Zhou and Zaiqiao Meng},
      year={2025},
      journal={arXiv preprint arXiv:2508.07407},
      url={https://arxiv.org/abs/2508.07407}, 
}

📚 Acknowledgements

This project builds upon several outstanding open-source projects: AFlow, TextGrad, DSPy, LiveCodeBench, and more. We would like to thank the developers and maintainers of these frameworks for their valuable contributions to the open-source community.

📄 License

Source code in this repository is made available under the MIT License.

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for EvoAgentX

Similar Open Source Tools

For similar tasks

For similar jobs