Building a Self-Evolving Ecosystem of AI Agents
[](https://evoagentx.org/)
[](https://EvoAgentX.github.io/EvoAgentX/)
[](https://discord.gg/SUEkfTYn)
[](https://x.com/EvoAgentX)
[](./assets/wechat_info.md)
[](https://star-history.com/#EvoAgentX/EvoAgentX)
[](https://github.com/EvoAgentX/EvoAgentX/fork)
[](https://github.com/EvoAgentX/EvoAgentX/blob/main/LICENSE)
An automated framework for evaluating and evolving agentic workflows.
## đĨ Latest News
- **[May 2025]** đ **EvoAgentX** has been officially released!
## ⥠Get Started
- [đĨ Latest News](#-latest-news)
- [⥠Get Started](#-get-started)
- [Installation](#installation)
- [LLM Configuration](#llm-configuration)
- [API Key Configuration](#api-key-configuration)
- [Configure and Use the LLM](#configure-and-use-the-llm)
- [Automatic WorkFlow Generation](#automatic-workflow-generation)
- [Demo Video](#demo-video)
- [⨠Final Results](#-final-results)
- [Evolution Algorithms](#evolution-algorithms)
- [đ Results](#-results)
- [Applications](#applications)
- [Tutorial and Use Cases](#tutorial-and-use-cases)
- [đ¯ Roadmap](#-roadmap)
- [đ Support](#-support)
- [Join the Community](#join-the-community)
- [Contact Information](#contact-information)
- [đ Contributing to EvoAgentX](#-contributing-to-evoagentx)
- [đ Acknowledgements](#-acknowledgements)
- [đ License](#-license)
## Installation
We recommend installing EvoAgentX using `pip`:
```bash
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](./docs/installation.md).
Example (optional, for local development):
```bash
git clone https://github.com/EvoAgentX/EvoAgentX.git
cd EvoAgentX
# Create a new conda environment
conda create -n evoagentx python=3.10
# 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:
```bash
export OPENAI_API_KEY=
```
- Windows Command Prompt:
```cmd
set OPENAI_API_KEY=
```
- Windows PowerShell:
```powershell
$env:OPENAI_API_KEY="" # " is required
```
Once set, you can access the key in your Python code with:
```python
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:
```bash
OPENAI_API_KEY=
```
Then load it in Python:
```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:
```python
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](./docs/modules/llm.md).
## 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:
```python
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`](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/workflow_demo.py)
## Demo Video
[](https://www.youtube.com/watch?v=Wu0ZydYDqgg)
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](https://www.nature.com/articles/s41586-025-08661-4), [MIPRO](https://arxiv.org/abs/2406.11695) and [AFlow](https://arxiv.org/abs/2410.10762).
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](https://github.com/EvoAgentX/EvoAgentX/blob/main/docs/tutorial/benchmark_and_evaluation.md) 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](https://huggingface.co/spaces/gaia-benchmark/leaderboard) benchmark. We select [Open Deep Research](https://github.com/huggingface/smolagents/tree/main/examples/open_deep_research) and [OWL](https://github.com/camel-ai/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
|
OWL Agent
|
> Full Optimization Reports: [Open Deep Research](https://github.com/eax6/smolagents) and [OWL](https://github.com/TedSIWEILIU/owl).
## Tutorial and Use Cases
> đĄ **New to EvoAgentX?** Start with the [Quickstart Guide](./docs/quickstart.md) for a step-by-step introduction.
Explore how to effectively use EvoAgentX with the following resources:
| Cookbook | Description |
|:---|:---|
| **[Build Your First Agent](./docs/tutorial/first_agent.md)** | Quickly create and manage agents with multi-action capabilities. |
| **[Build Your First Workflow](./docs/tutorial/first_workflow.md)** | Learn to build collaborative workflows with multiple agents. |
| **[Automatic Workflow Generation](./docs/quickstart.md#automatic-workflow-generation-and-execution)** | Automatically generate workflows from natural language goals. |
| **[Benchmark and Evaluation Tutorial](./docs/tutorial/benchmark_and_evaluation.md)** | Evaluate agent performance using benchmark datasets. |
| **[TextGrad Optimizer Tutorial](./docs/tutorial/textgrad_optimizer.md)** | Automatically optimise the prompts within multi-agent workflow with TextGrad. |
| **[AFlow Optimizer Tutorial](./docs/tutorial/aflow_optimizer.md)** | Automatically optimise both the prompts and structure of multi-agent workflow with AFlow. |
đ ī¸ 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](https://discord.gg/SUEkfTYn) â Chat, discuss, and collaborate in real-time.
- [X (formerly Twitter)](https://x.com/EvoAgentX) â Follow us for news, updates, and insights.
- [WeChat](https://github.com/EvoAgentX/EvoAgentX/blob/main/assets/wechat_info.md) â Connect with our Chinese community.
### Contact Information
If you have any questions or feedback about this project, please feel free to contact us. We highly appreciate your suggestions!
- **Email:** evoagentx.ai@gmail.com
We will respond to all questions within 2-3 business days.
## đ 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](https://github.com/EvoAgentX/EvoAgentX/blob/main/CONTRIBUTING.md) which outlines the steps for contributing to EvoAgentX. Please refer to this guide to ensure smooth collaboration and successful contributions. đ¤đ
[](https://www.star-history.com/#EvoAgentX/EvoAgentX&Date)
## đ Acknowledgements
This project builds upon several outstanding open-source projects: [AFlow](https://github.com/FoundationAgents/MetaGPT/tree/main/metagpt/ext/aflow), [TextGrad](https://github.com/zou-group/textgrad), [DSPy](https://github.com/stanfordnlp/dspy), [LiveCodeBench](https://github.com/LiveCodeBench/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](./LICENSE).
