跳到主要内容

EvoAgentX — 顶层全景与阅读地图

30 秒导读: EvoAgentX 是一个把"多智能体工作流"当软件一样自动构建、自动评测、自动改进的开源框架。你给一句话目标,它生成一张可执行的多智能体工作流图并跑出结果;你再给一个数据集,它用进化算法反复改这张图,让它在任务上越跑越准。本章只做顶层导航——讲清它是什么、五大块怎么拼、两条主线怎么走,以及后面 6 章按什么顺序读;任何子系统的实现细节都留给对应章节。

1. 这是什么(零基础也能懂)​

一句话定义: EvoAgentX 是一个用于构建、评测、进化基于 LLM 的智能体工作流的框架——目标驱动、模块化、可自动演化。这句话的事实取自仓库 README.md「What is EvoAgentX」一节(README.md:38-39)。

它想解决的痛: 今天用 LLM 搭多智能体系统,通常是人手写一长串 prompt、手工把几个 agent 串起来(所谓"prompt chaining / manual orchestration")。这套东西又脆又难调:改一个环节要人肉重连,想知道"好不好"只能凭感觉,想变好只能继续手调。EvoAgentX 的立场是:别再手工编排了——把工作流当成"可以被持续测试和改进的软件"。

三件事,对应三个阶段,构成一个闭环:

阶段白话你要给什么框架产出什么
构建(Autoconstruction)一句话变成一套多智能体流程一句话目标可执行的 WorkFlowGraph
评测(Evaluation)给流程打分一个数据集 + 评分标准指标分数(如准确率)
进化(Self-Evolution)照分数把流程改得更好上面两样一张更优的工作流/prompt

最小使用直觉(路径一:一句话 → 结果): 下面这段来自 examples/workflow/workflow_demo.py:23-37,是"给目标 → 生成 → 执行"的完整骨架。

# 示意,提炼自 examples/workflow/workflow_demo.py:23-37
goal = "Generate html code for the Tetris game that can be played in the browser."

# ① 从一句话目标自动生成一张多智能体工作流图
wf_generator = WorkFlowGenerator(llm=llm)
workflow_graph = wf_generator.generate_workflow(goal=goal)

# ② 按图里每个任务的要求,批量把 agent 实例化出来
agent_manager = AgentManager()
agent_manager.add_agents_from_workflow(workflow_graph, llm_config=openrouter_config)

# ③ 执行整张图,拿到最终结果
workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)
result = workflow.execute(extract_output=True)   # 重点看这一行:整套流程在这里跑完

最小使用直觉(路径二:工作流 + 数据集 → 更优工作流): 下面来自 examples/optimization/textgrad/math_textgrad.py:63-102,是"拿一张已有工作流,让优化器在 benchmark 上把它改好"。

# 示意,提炼自 examples/optimization/textgrad/math_textgrad.py:63-102
workflow_graph = SequentialWorkFlowGraph.from_dict(math_graph_data)  # 一张已有工作流
benchmark = MATH(...)                                                # 一个带答案的数据集

optimizer = TextGradOptimizer(graph=workflow_graph, optimize_mode="all", ...)
optimizer.evaluate(dataset=benchmark, eval_mode="test")   # 优化前:先测一遍基线
optimizer.optimize(benchmark, seed=8)                     # 迭代改进(核心一行)
optimizer.restore_best_graph()                            # 回到迭代中最好的那张图
optimizer.evaluate(dataset=benchmark, eval_mode="test")   # 优化后:再测,看提升

一句话类比: 把工作流想成一段"会自己做单元测试、还会照测试结果自动重构的代码"——WorkFlowGenerator 是脚手架生成器,Evaluator 是测试套件,Optimizer 是那个不知疲倦、照着分数一遍遍改代码的实习生。

2. 顶层全景(五大块怎么拼)​

EvoAgentX 的代码全在 evoagentx/ 包下。可以把它切成五大纵向块 + 一层横向能力。

怎么读下面这张图: 从上到下是"越来越高层"——最底下是所有对象共享的地基,往上是执行单元,再往上是把单元编排起来的工作流引擎;左上的自动构建器负责"造图",右侧的进化优化器 + 评测负责"改图";最右一列的工具/记忆/RAG/HITL 是横切能力,插到 agent 身上让它能动手、能记忆、能被人管。

                          一句话目标 goal
                               │
              ┌────────────────▼─────────────────┐
              │  ④ 自动构建器 workflow_generator   │   TaskPlanner → AgentGenerator
              │     (拆任务 → 造 agent → 连成图)   │
              └────────────────┬─────────────────┘
                               │ 产出
                    ┌──────────▼───────────┐        ┌──────────────────────┐
                    │ ③ 工作流引擎 workflow/ │        │  横向能力(插到 agent) │
                    │  WorkFlowGraph 存结构 │◄──────►│  tools/  工具:动手     │
                    │  WorkFlowManager 调度 │  用     │  memory/ 记忆:短/长期  │
                    │  Environment 记轨迹   │        │  rag/    检索增强       │
                    └──────────┬───────────┘        │  hitl/   人在环中审批   │
                               │ 每个任务交给         └──────────────────────┘
                    ┌──────────▼───────────┐
                    │ ② 执行单元 agents/ actions/│
                    │  Agent 持有多个 Action    │
                    │  Action = 一次结构化LLM调用│
                    └──────────┬───────────┘
                               │ 都建立在
                    ┌──────────▼───────────┐
                    │ ① 地基 core/           │  BaseModule 自动注册 + 序列化
                    │  Message 消息 / Parser  │  LLM 输出解析
                    └──────────────────────┘

        ⑤ 进化:optimizers/ ── 反复调用 evaluators/ + benchmark/ 给"图"打分并改进
                (AFlow / TextGrad / MIPRO / SEW / MapElites …)

部件一句话职责(部件 | 职责 | 主要文件):

部件职责主要文件(相对克隆根)
① 核心地基所有对象的共同基类:自动注册、存/取(序列化)、消息、LLM 输出解析evoagentx/core/module.py、core/registry.py、core/message.py、models/base_model.py
② Agent / Action执行单元:Agent 持有若干 Action,Action 把一次 LLM 调用变成结构化输出evoagentx/agents/agent.py、agents/customize_agent.py、actions/action.py
③ 工作流引擎存工作流结构(图)、调度下一个任务/动作、记录执行轨迹evoagentx/workflow/workflow_graph.py、workflow/workflow.py、workflow/workflow_manager.py、workflow/environment.py
④ 自动构建器从一句话目标拆子任务、造 agent、连成可运行工作流evoagentx/workflow/workflow_generator.py、agents/task_planner.py、agents/agent_generator.py
⑤ 进化优化器 + 评测在数据集上给工作流打分,并用进化算法迭代改进evoagentx/optimizers/*.py、evaluators/evaluator.py、benchmark/benchmark.py
横向:工具让 agent 真正动手:代码执行、搜索、文件、数据库、浏览器…evoagentx/tools/tool.py(Tool/Toolkit)及同目录各 *_tool.py
横向:记忆短期与长期记忆evoagentx/memory/long_term_memory.py、memory/memory_manager.py
横向:RAG检索增强:分块、向量化、检索evoagentx/rag/rag.py(RAGEngine)
横向:HITL人在环中:执行前审批、收集人类输入evoagentx/hitl/approval_manager.py(HITLManager)

一个容易忽略但很关键的事实:这五块不是各写各的——它们几乎全部继承自同一个 BaseModule(core/module.py:51)。工作流图、agent、action、优化器都能用同一套 save_module / from_dict 存取,也都在导入时自动登记进 MODULE_REGISTRY(core/registry.py:21)。这就是"一张工作流能被存成 JSON、被优化器读进来改、再存回去"能成立的底层原因(细节见 01-core-foundation.md)。

3. 主线走一遍(高层,不进代码)​

路径一:一句话目标 → 可执行工作流​

高层四步,对应第 2 节图里 ④→③→②:

goal(一句话)
   │  WorkFlowGenerator.generate_workflow(goal)          workflow/workflow_generator.py:100
   ▼
① TaskPlanner 把目标拆成带依赖的子任务(plan)
   │
② build_workflow_from_plan 把 plan 连成 WorkFlowGraph    workflow/workflow_generator.py:201
   │
③ AgentGenerator 给每个子任务生成/指派一个 agent
   ▼
可执行的 WorkFlowGraph
   │  AgentManager.add_agents_from_workflow(...)          agents/agent_manager.py:204
   │  WorkFlow.execute(...)                               workflow/workflow.py:96
   ▼
WorkFlowManager 反复"挑下一个就绪任务 → 派 agent 执行 → 把结果写进 Environment",直到图跑完
   ▼
最终结果 WorkflowResult

真源码锚点:生成入口 WorkFlowGenerator.generate_workflow(workflow/workflow_generator.py:100)内部依次调 TaskPlanner(拆解)、build_workflow_from_plan(建图,:201)、generate_agents(造 agent);执行侧 WorkFlow.execute(workflow/workflow.py:96)驱动 WorkFlowManager.schedule_next_task(workflow/workflow_manager.py:431)一轮轮往前推。展开见 04-auto-construction.md 与 03-workflow-execution.md。

路径二:工作流 + 数据集 → 迭代改进​

这条是 EvoAgentX 名字里"Evo"的所在。给定一张工作流和一个带标准答案的 benchmark,优化器在"评测 → 改 → 再评测"里打转:

现有 WorkFlowGraph  +  Benchmark(带答案的数据集)
   │
   ▼
Optimizer.optimize(dataset)                 optimizers/optimizer.py:23(抽象接口)
   │
   ├─(loop)→ step():对图/prompt 做一次改动(不同算法改法不同)
   │            AFlow=蒙特卡洛搜图  TextGrad=文本梯度改 prompt
   │            MIPRO=贝叶斯调指令+示例  SEW=进化式重写
   │
   └─(loop)→ evaluate():用 Evaluator 在 Benchmark 上跑一遍打分
                optimizers/optimizer.py:35 → evaluators/evaluator.py:74
   ▼
保留分最高的那张图(restore_best_graph)

真源码锚点:所有优化器都实现同一个抽象基类 Optimizer(optimizers/optimizer.py:12)的 optimize(:23)/step(:29)/evaluate(:35);评分统一走 Evaluator.evaluate(evaluators/evaluator.py:74)。展开见 05-self-evolution-optimizers.md。

4. 阅读地图(建议顺序 + 每章一句话)​

按"地基 → 单元 → 编排 → 构建 → 进化 → 横向能力"由浅入深读:

顺序章节一句话讲什么
101-core-foundation.md地基:BaseModule 的自动注册表与序列化、Message 消息、LLM 输出如何被解析成结构化对象——理解它,后面每块的"存/取/路由"都通了。
202-agents-actions.md执行单元:Agent 怎样持有多个 Action,Action 怎样把一次 LLM 调用变成校验过的结构化输出,以及 CustomizeAgent 如何零代码造 agent。
303-workflow-execution.md编排与执行:WorkFlowGraph 存什么,WorkFlowManager 如何调度下一个任务/动作,Environment 如何记录整条执行轨迹。
404-auto-construction.md自动构建:WorkFlowGenerator 如何经 TaskPlanner→AgentGenerator 把一句话目标变成可运行的多智能体工作流。
505-self-evolution-optimizers.md自演化引擎:评测闭环(Evaluator+Benchmark)与优化器家族(AFlow / TextGrad / MIPRO / SEW / MapElites)各自的改进思路。
606-tools-memory-rag-hitl.md横向能力:工具生态(Toolkit)、短/长期记忆、RAG 检索与人机协作(HITL),让 agent 能动手、能记忆、被人管。

只想快速取用的读法: 想跑起来 → 读第 3、4 章;想让流程自己变好 → 直奔第 5 章;想给 agent 加工具/记忆 → 第 6 章;想改框架底层或自定义可序列化对象 → 第 1 章。

5. 巧妙之处速览​

留几个"值得带走"的设计,细节在各章展开,这里只点破妙在哪:

  • 一切皆 BaseModule,靠元类自动登记。 MetaModule(core/module.py:24)是所有对象的元类,类一被定义就自动写进 MODULE_REGISTRY(core/registry.py:21)。好处:JSON 里存个 class_name 就能反查类、重建对象——这正是"工作流能存盘、被优化器读回来改"的地基。
  • 优化器与执行引擎解耦在同一个抽象接口后。 五种风格迥异的优化算法(搜图、文本梯度、贝叶斯、进化…)全部塞进同一个 Optimizer(optimizers/optimizer.py:12)的 optimize/step/evaluate 三件套,换算法只换类,评测口径不变。
  • 调度是"LLM 决定下一步",不是死循环。 WorkFlowManager 用 TaskScheduler(workflow/workflow_manager.py:46)/ActionScheduler(:207)这类 Action 让模型来挑"下一个该跑哪个任务/动作",而不是写死的拓扑序——工作流因此能带条件分支地推进。
  • 工具与 agent 的"造图"打通。 WorkFlowGenerator 接收 tools 列表并在造 agent 时按需分配(workflow/workflow_generator.py:41,52),于是"给这个流程配上 arXiv 工具"这种需求无需改代码就能进到生成出的 agent 里。
  • 零代码造 agent。 CustomizeAgent(agents/customize_agent.py:36)让你用配置(prompt + 输入/输出字段)就声明一个 agent,不必写子类——大幅降低搭工作流的门槛。

6. 代码地图(顶层导航索引)​

顶层跳转表(主题 | 文件 | 符号名);想深入某块请转对应章节。

主题文件(相对克隆根)符号名
所有对象的基类(注册+序列化)evoagentx/core/module.pyBaseModule、MetaModule、from_dict、save_module
全局注册表evoagentx/core/registry.pyMODULE_REGISTRY、register_module、ModelRegistry
消息 / LLM 输出解析evoagentx/core/message.py、evoagentx/models/base_model.pyMessage、LLMOutputParser、BaseLLM
执行单元:Agentevoagentx/agents/agent.py、evoagentx/agents/customize_agent.pyAgent、CustomizeAgent、add_action
执行单元:Actionevoagentx/actions/action.pyAction、ActionInput、ActionOutput
agent 批量装配evoagentx/agents/agent_manager.pyAgentManager、add_agents_from_workflow
工作流结构(图)evoagentx/workflow/workflow_graph.pyWorkFlowGraph、WorkFlowNode、WorkFlowEdge、SequentialWorkFlowGraph
执行入口evoagentx/workflow/workflow.pyWorkFlow、execute、execute_task
调度器evoagentx/workflow/workflow_manager.pyWorkFlowManager、schedule_next_task、TaskScheduler、ActionScheduler
执行轨迹evoagentx/workflow/environment.pyEnvironment、TrajectoryState
自动构建evoagentx/workflow/workflow_generator.pyWorkFlowGenerator、generate_workflow、build_workflow_from_plan
规划 / 造 agentevoagentx/agents/task_planner.py、evoagentx/agents/agent_generator.pyTaskPlanner、AgentGenerator
优化器抽象接口evoagentx/optimizers/optimizer.pyOptimizer、optimize、step、evaluate
优化器家族evoagentx/optimizers/*.pyAFlowOptimizer、TextGradOptimizer、MiproOptimizer、SEWOptimizer、MapElitesOptimizer
评测 / 数据集evoagentx/evaluators/evaluator.py、evoagentx/benchmark/benchmark.pyEvaluator、Benchmark
工具生态evoagentx/tools/tool.pyTool、Toolkit
记忆evoagentx/memory/long_term_memory.py、evoagentx/memory/memory_manager.pyLongTermMemory、MemoryManager
RAGevoagentx/rag/rag.pyRAGEngine
人机协作evoagentx/hitl/approval_manager.pyHITLManager

顶层导航到此为止。要看某块"怎么实现的",按第 4 节阅读地图进对应章节;所有引用 as-of sourceCommit: aad19b912f640161ea07e8904d9237cd34fde5f1。